fix(permissions): rename sets to authWrite (single-segment NSID under namespace root)

The previous NSIDs `org.hypercerts.permissions.crud` / `app.certified.permissions.crud`
were INVALID: a permission set may only grant permissions under its own NSID
authority, and NSID.authority is the reversed domain of all-but-the-last
segment. The `.permissions.` segment made the authority `permissions.hypercerts.org`,
which does not parent `org.hypercerts.claim.*` — so IncludeScope.toScopes
silently expanded the set to ZERO scopes.

Rename to a single leaf directly under the namespace root, matching Bluesky's
real published permission sets (app.bsky.authViewAll / authCreatePosts /
authDeleteContent / authFullApp — single segment, auth-prefixed capability leaf)
and the spec's illustrative com.example.authFull:

- org.hypercerts.authWrite  (lexicons/org/hypercerts/authWrite.json)
- app.certified.authWrite   (lexicons/app/certified/authWrite.json)

Each now expands correctly to one combined repo: scope covering all its
collections (verified).

Also: replace the path-based codegen exclusion (which assumed a permissions/
subdir) with scripts/codegen-lexicon-files.js — a content-based file list
(main.type === "permission-set") shared as the single source of truth with
generate-exports.js, so the exclusion no longer breaks when set files move.

Docs/skill/changeset updated for the new NSIDs, the single-segment-NSID
rationale, and the combined-scope expansion shape. npm run check passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aspiers

.agents/skills/building-with-hypercerts-lexicons/SKILL.md

@@ -198,15 +198,15 @@ collection write needs a `repo:<collection>?action=…` scope. Rather than list
 every collection by hand, request a **permission set** — a published bundle —
 with a single `include:` scope:
 
-| Permission set NSID               | Grants write (create/update/delete) on    |
-| --------------------------------- | ----------------------------------------- |
-| `org.hypercerts.permissions.crud` | all `org.hypercerts.*` record collections |
-| `app.certified.permissions.crud`  | all `app.certified.*` record collections  |
+| Permission set NSID        | Grants write (create/update/delete) on    |
+| -------------------------- | ----------------------------------------- |
+| `org.hypercerts.authWrite` | all `org.hypercerts.*` record collections |
+| `app.certified.authWrite`  | all `app.certified.*` record collections  |
 
 In your OAuth client's authorization request, ask for the set(s) you need:
 
 ```text
-scope: include:org.hypercerts.permissions.crud
+scope: include:org.hypercerts.authWrite
 ```
 
 The user's PDS resolves the published set and expands it into the underlying

.changeset/permission-sets-crud.md

@@ -2,7 +2,7 @@
 "@hypercerts-org/lexicon": minor
 ---
 
-Add two permission-set lexicons — `org.hypercerts.permissions.crud` and `app.certified.permissions.crud` — each granting create/update/delete over every record collection in its namespace.
+Add two permission-set lexicons — `org.hypercerts.authWrite` and `app.certified.authWrite` — each granting create/update/delete over every record collection in its namespace.
 
 A [permission set](https://atproto.com/specs/permission#permission-sets) lets any AT Protocol app request a whole bundle of `repo:` scopes with a single `include:<nsid>` OAuth scope, instead of enumerating each collection by hand. The user's PDS resolves and expands the set during the OAuth grant; the same published set can also be consumed by services (e.g. the Certified group service) when expanding API-key scopes.
 

SCHEMAS.md

@@ -299,6 +299,12 @@ A free-text string value (e.g. a display name, wallet address, or other identifi
 
 ---
 
+### `org.hypercerts.permissions.crud`
+
+**Description:** Permission set granting create, update, and delete on every Hypercerts (org.hypercerts) record collection.
+
+---
+
 ### `org.hypercerts.workscope.cel`
 
 **Description:** A structured, machine-evaluable work scope definition using CEL (Common Expression Language). Tags referenced in the expression correspond to org.hypercerts.workscope.tag keys. See https://github.com/google/cel-spec. Note: this is intentionally type 'object' (not 'record') so it can be directly embedded inline in union types (e.g., activity.workScope) without requiring a separate collection or strongRef indirection.
@@ -541,6 +547,12 @@ The EIP-712 typed data message that was signed by the wallet. Contains the field
 
 ---
 
+### `app.certified.permissions.crud`
+
+**Description:** Permission set granting create, update, and delete on every Certified (app.certified) record collection.
+
+---
+
 ### `app.certified.signature.defs`
 
 **Description:** Common type definitions for cryptographic signatures attached to records, per the ATProtocol Attestation Specification.

docs/design/permission-sets.md

@@ -36,7 +36,7 @@ These are general AT Protocol artifacts, not specific to any one service. The
 expected consumers, in rough order of generality:
 
 1. **Any atproto app working with Hypercerts / Certified data directly.** An
-   OAuth client requests `include:org.hypercerts.permissions.crud` (and/or the
+   OAuth client requests `include:org.hypercerts.authWrite` (and/or the
    `app.certified.*` set) in its authorization request; the user's PDS expands it
    and the app reads/writes those collections in the user's own repo. No
    intermediary is involved. This is the broadest case.
@@ -60,38 +60,49 @@ We define two **record-collection write** sets — one per data namespace in thi
 repo. Each grants the three `repo:` write actions — create, update, delete —
 over all of that namespace's record collections.
 
-| Set NSID                          | Grants write (create/update/delete) on    |
-| --------------------------------- | ----------------------------------------- |
-| `org.hypercerts.permissions.crud` | all `org.hypercerts.*` record collections |
-| `app.certified.permissions.crud`  | all `app.certified.*` record collections  |
+| Set NSID                   | Grants write (create/update/delete) on    |
+| -------------------------- | ----------------------------------------- |
+| `org.hypercerts.authWrite` | all `org.hypercerts.*` record collections |
+| `app.certified.authWrite`  | all `app.certified.*` record collections  |
 
 Both are authored and published from **this repository**, which is the namespace
 authority for both — see _Namespace authority_ below.
 
-> **"CRUD" but no read action.** The leaf is `crud` as a familiar shorthand, but
-> a `repo:` permission has only three actions — `create`, `update`, `delete`
-> (there is no `read` action in the scope grammar). Reading records needs **no
-> permission at all**: atproto repo records are public and world-readable via
-> `com.atproto.repo.getRecord` / `listRecords`, with no scope required. So a
-> "CRUD" set covers the only parts of CRUD that _are_ permissioned — the writes —
-> and "read" is implicitly available to everyone. The user-facing `title` /
-> `detail` (the authorization-dialog consent copy) describe this in plain terms —
-> "Manage your … data" / "Create, edit, and delete …" — deliberately not implying
-> any grantable read scope exists.
-
-> **Naming.** The spec prescribes no naming convention: a permission set is
-> identified only by `type: "permission-set"` in its `main` def, and its sole
-> examples are illustrative (`com.example.authFull`). The `permissions.crud`
-> leaf is a house choice for this repo; rename freely.
-
-### `org.hypercerts.permissions.crud`
+> **Write only — no read action.** The leaf is `authWrite` because a `repo:`
+> permission has only three actions — `create`, `update`, `delete` (there is no
+> `read` action in the scope grammar). Reading records needs **no permission at
+> all**: atproto repo records are public and world-readable via
+> `com.atproto.repo.getRecord` / `listRecords`, with no scope required. So these
+> sets cover the only repo operations that _are_ permissioned — the writes — and
+> "read" is implicitly available to everyone. The user-facing `title` / `detail`
+> (the authorization-dialog consent copy) say "Manage your … data" / "Create,
+> edit, and delete …" accordingly.
+
+> **Naming — and why the NSID is a single segment under the namespace root.**
+> Two constraints, one of them hard:
+>
+> 1. **The set NSID's authority must parent the collections it grants** (the
+>    namespace-authority rule below). `NSID.authority` is the reversed domain of
+>    _all but the last segment_, so a set named `org.hypercerts.permissions.crud`
+>    has authority `permissions.hypercerts.org`, which does **not** parent
+>    `org.hypercerts.claim.*` — `IncludeScope.toScopes` would silently return an
+>    empty list. The set NSID must therefore be a **single leaf directly under the
+>    namespace root** (`org.hypercerts.<leaf>`), whose authority is `hypercerts.org`.
+> 2. **Convention follows real precedent.** Bluesky publishes its own permission
+>    sets exactly this way — single segment under the namespace, `auth`-prefixed
+>    capability leaf: `app.bsky.authViewAll`, `app.bsky.authCreatePosts`,
+>    `app.bsky.authDeleteContent`, `app.bsky.authFullApp`. The spec's illustrative
+>    examples (`com.example.authFull`, `com.example.authBasicFeatures`) match. So
+>    `authWrite` mirrors that style: `auth`-prefixed, names the capability.
+
+### `org.hypercerts.authWrite`
 
 Enumerates every `type: "record"` collection under `org.hypercerts.*`:
 
 ```jsonc
 {
   "lexicon": 1,
-  "id": "org.hypercerts.permissions.crud",
+  "id": "org.hypercerts.authWrite",
   "defs": {
     "main": {
       "type": "permission-set",
@@ -123,14 +134,14 @@ Enumerates every `type: "record"` collection under `org.hypercerts.*`:
 }
 ```
 
-### `app.certified.permissions.crud`
+### `app.certified.authWrite`
 
 Enumerates every `type: "record"` collection under `app.certified.*`:
 
 ```jsonc
 {
   "lexicon": 1,
-  "id": "app.certified.permissions.crud",
+  "id": "app.certified.authWrite",
   "defs": {
     "main": {
       "type": "permission-set",
@@ -202,8 +213,11 @@ not what these sets are for.)
 
 A `repo:` scope targets the **user's own repo**, so it has no audience. Both sets
 here are `repo:`-only, so an `include:` for them is requested **without** any
-`?aud=` parameter, and expands to plain
-`repo:<collection>?action=create&action=update&action=delete` scopes.
+`?aud=` parameter. Each set expands to a **single combined `repo:` scope** that
+lists every collection — `IncludeScope.toScopes` coalesces the permission's
+collection array into one scope string
+(`repo:?collection=<a>&collection=<b>&…&action=create&action=update&action=delete`),
+rather than emitting one scope per collection.
 
 (For completeness: an `rpc:` permission _does_ take an `aud` naming the target
 service, and a set can let the `include:`'s `?aud=` flow into `rpc:` permissions
@@ -270,7 +284,7 @@ the `type: "record"` defs in its namespace).
 > [#219](https://github.com/hypercerts-org/hypercerts-lexicon/pull/219)
 > (`feat/signature-support-v2`, HYPER-181) adds the `app.certified.signature.proof`
 > record lexicon, which does **not** exist on `main` yet and so is **not** in
-> `app.certified.permissions.crud` here. When #219 merges,
+> `app.certified.authWrite` here. When #219 merges,
 > `app.certified.signature.proof` must be added to the set's `collection` list
 > (and re-published). The two PRs touch different files, so neither blocks the
 > other — this is just a follow-up to land after both.

…cons/app/certified/permissions/crud.json lexicons/app/certified/authWrite.jsonlexicons/app/certified/permissions/crud.json renamed to lexicons/app/certified/authWrite.json lexicons/app/certified/permissions/crud.json renamed to lexicons/app/certified/authWrite.json

@@ -1,6 +1,6 @@
 {
   "lexicon": 1,
-  "id": "app.certified.permissions.crud",
+  "id": "app.certified.authWrite",
   "defs": {
     "main": {
       "type": "permission-set",

…ons/org/hypercerts/permissions/crud.json lexicons/org/hypercerts/authWrite.jsonlexicons/org/hypercerts/permissions/crud.json renamed to lexicons/org/hypercerts/authWrite.json lexicons/org/hypercerts/permissions/crud.json renamed to lexicons/org/hypercerts/authWrite.json

@@ -1,6 +1,6 @@
 {
   "lexicon": 1,
-  "id": "org.hypercerts.permissions.crud",
+  "id": "org.hypercerts.authWrite",
   "defs": {
     "main": {
       "type": "permission-set",

package.json

@@ -42,12 +42,12 @@
     "check": "npm run gen-api && npm run lint && npm run typecheck && npm run build && npm run test",
     "build": "rollup -c && npm run build:types",
     "build:types": "tsc --project tsconfig.build.json",
-    "//permissions": "permission-set lexicons (lexicons/**/permissions/*.json) are published as-is but have no TS shape; lex gen-* cannot codegen them, so they are excluded from the codegen globs below.",
-    "gen-api": "find ./lexicons -name '*.json' -not -path '*/permissions/*' | xargs lex gen-api --yes ./generated && npm run gen-index",
-    "gen-md": "find ./lexicons -name '*.json' -not -path '*/permissions/*' | xargs lex gen-md --yes ./lexicons.md",
+    "//permissions": "permission-set lexicons are published as-is but have no TS shape; lex gen-* cannot codegen them. scripts/codegen-lexicon-files.js lists the lexicons to codegen, excluding permission-sets by content (single source of truth shared with generate-exports.js).",
+    "gen-api": "lex gen-api --yes ./generated $(node ./scripts/codegen-lexicon-files.js) && npm run gen-index",
+    "gen-md": "lex gen-md --yes ./lexicons.md $(node ./scripts/codegen-lexicon-files.js)",
     "gen-schemas-md": "node ./scripts/generate-schemas.js",
     "//gen-ts": "UNUSED - use gen-api instead",
-    "gen-ts": "find ./lexicons -name '*.json' -not -path '*/permissions/*' | xargs lex gen-ts-obj > generated/DO-NOT-USE-lexicons.ts",
+    "gen-ts": "lex gen-ts-obj $(node ./scripts/codegen-lexicon-files.js) > generated/DO-NOT-USE-lexicons.ts",
     "gen-index": "node ./scripts/generate-exports.js",
     "lex": "lex",
     "test": "vitest run",

scripts/codegen-lexicon-files.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Print the list of lexicon JSON files that `lex gen-*` should process, one per
+ * line — i.e. every lexicon under `lexicons/` EXCEPT permission-set lexicons.
+ *
+ * `lex gen-api` / `gen-md` / `gen-ts` cannot codegen a `type: "permission-set"`
+ * def (it has no TypeScript shape and the CLI throws on it). Permission sets are
+ * published as-is, so they must be excluded from the codegen globs.
+ *
+ * This is the **single source of truth** for that exclusion — both the codegen
+ * scripts (via this list) and `scripts/generate-exports.js` (via the same
+ * `main.type === "permission-set"` check) skip the same files by **content**,
+ * not by path, so they cannot drift as files move.
+ *
+ * Usage (in package.json): `lex gen-api --yes ./generated $(node ./scripts/codegen-lexicon-files.js)`
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const lexiconsDir = fileURLToPath(new URL("../lexicons", import.meta.url));
+
+function findJsonFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findJsonFiles(full));
+    else if (entry.isFile() && entry.name.endsWith(".json")) out.push(full);
+  }
+  return out;
+}
+
+function isPermissionSet(file) {
+  try {
+    return (
+      JSON.parse(readFileSync(file, "utf-8"))?.defs?.main?.type ===
+      "permission-set"
+    );
+  } catch {
+    return false; // let lex surface a parse error rather than silently skip
+  }
+}
+
+const files = findJsonFiles(lexiconsDir)
+  .filter((f) => !isPermissionSet(f))
+  .sort();
+
+process.stdout.write(files.join("\n") + "\n");