feat(permissions): implement org.hypercerts and app.certified write permission sets

Add the two permission-set lexicons designed in docs/design/permission-sets.md:

- org.hypercerts.permissions.crud  — write (create/update/delete) over all
                                     org.hypercerts.* record collections
- app.certified.permissions.crud   — write (create/update/delete) over all
                                     app.certified.* record collections

TWO sets, not one combined set, because the spec mandates it: a permission set
"is limited to expressing permissions that reference resources under the same
NSID namespace as the set itself" and "can not address 'sibling groups' or
'parents'" (https://atproto.com/specs/permission#permission-sets).
org.hypercerts and app.certified are different namespace authorities, so they
cannot legally be combined in one set. An app needing both requests both
include: scopes. Each set also enumerates its collections explicitly (the spec
forbids wildcards inside a permission set).

permission-set is a lexicon primitive that lex gen-api cannot codegen (it has
no TypeScript shape), so these files are published as-is but excluded from the
codegen globs (gen-api/gen-md/gen-ts) and from generated/exports.ts (filtered
by main def type, parsing each lexicon once). They still appear in SCHEMAS.md
and are JSON-parsed by the schema/test pipeline. The full `npm run check`
(gen-api, lint, typecheck, build, test, style) passes.

The human-readable title/detail are written as authorization-dialog consent
copy: plain-language, concise, naming recognizable record categories.

Also documents the permission sets in the building-with-hypercerts-lexicons
skill (how to request them as OAuth scopes).

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

Author: aspiers

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

@@ -190,6 +190,40 @@ if (result.success) {
 }
 ```
 
+## Permission Sets (OAuth scopes)
+
+To **write** Hypercerts or Certified records to a user's repo, your app needs
+the user's authorization. AT Protocol grants this via OAuth scopes: each
+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  |
+
+In your OAuth client's authorization request, ask for the set(s) you need:
+
+```text
+scope: include:org.hypercerts.permissions.crud
+```
+
+The user's PDS resolves the published set and expands it into the underlying
+`repo:` scopes on the consent screen, where the user sees the set's plain-language
+description (e.g. "Manage your Hypercerts data"). Notes:
+
+- **Two sets, never one.** A permission set may only reference its own namespace
+  authority (atproto permission spec), so `org.hypercerts.*` and
+  `app.certified.*` cannot share a set. An app needing both requests **both**
+  `include:` scopes.
+- **Writes only.** These cover create/update/delete. **Reading** records needs no
+  scope at all — atproto repo records are public.
+- **`repo:` scopes carry no `aud`** — request the `include:` without an `?aud=`.
+- These same published sets are also consumed by the Certified group service
+  (CGS) when it expands an API key's `include:` scope — see the CGS integration
+  guide.
+
 ## Lexicon Overview
 
 ### Claims — the core impact record
@@ -673,6 +707,8 @@ avoid typos.
 ## Further Reading
 
 - [SCHEMAS.md](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/SCHEMAS.md) — full property-level documentation for every lexicon
+- [docs/design/permission-sets.md](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/docs/design/permission-sets.md) — the permission sets and how they are consumed (OAuth + CGS API keys)
+- [ATProto permission spec](https://atproto.com/specs/permission#permission-sets) — OAuth scopes and permission sets
 - [CHANGELOG.md](https://github.com/hypercerts-org/hypercerts-lexicon/blob/main/CHANGELOG.md) — version history and migration guides
 - [ATProto Lexicon Guide](https://atproto.com/guides/lexicon) — AT Protocol lexicon fundamentals
 - [ATProto Lexicon Style Guide](https://atproto.com/guides/lexicon-style-guide) — schema design conventions

.changeset/permission-sets-crud.md

@@ -0,0 +1,13 @@
+---
+"@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.
+
+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.
+
+There are **two** sets rather than one because the spec requires it: a permission set "is limited to expressing permissions that reference resources under the same NSID namespace as the set itself" and "can not address 'sibling groups' or 'parents'". `org.hypercerts` and `app.certified` are separate namespace authorities, so they cannot be combined in a single set — an app needing both requests both `include:` scopes.
+
+Permission sets are published as-is (they are the source of truth for what gets published to AT Protocol) but have no TypeScript shape — `lex gen-api` cannot generate code for `permission-set` defs. They are therefore excluded from the codegen globs (`gen-api`/`gen-md`/`gen-ts`) and from `generated/exports.ts`, while still shipping as raw lexicon JSON.
+
+Collection lists are enumerated explicitly because the spec forbids wildcards inside a permission set; they must be kept in sync as record types are added. See `docs/design/permission-sets.md`.

docs/design/permission-sets.md

@@ -56,18 +56,29 @@ key-creation — reads the same published definition.
 
 ## The sets
 
-We define two **record-collection CRUD** sets — one per data namespace in this
-repo. Each grants create/update/delete over all of that namespace's record
-collections.
+We define two **record-collection write** sets — one per data namespace in this
+repo. Each grants the three `repo:` write actions — create, update, delete —
+over all of that namespace's record collections.
 
-| Set NSID                          | Grants CRUD on                            |
+| 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  |
 
 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`
@@ -84,7 +95,9 @@ Enumerates every `type: "record"` collection under `org.hypercerts.*`:
   "defs": {
     "main": {
       "type": "permission-set",
-      "title": "Full CRUD on Hypercerts record collections",
+      "description": "Permission set granting create, update, and delete on every Hypercerts (org.hypercerts) record collection.",
+      "title": "Manage your Hypercerts data",
+      "detail": "Create, edit, and delete your Hypercerts records (impact claims, evaluations, funding, and related data).",
       "permissions": [
         {
           "type": "permission",
@@ -121,7 +134,9 @@ Enumerates every `type: "record"` collection under `app.certified.*`:
   "defs": {
     "main": {
       "type": "permission-set",
-      "title": "Full CRUD on Certified record collections",
+      "description": "Permission set granting create, update, and delete on every Certified (app.certified) record collection.",
+      "title": "Manage your Certified data",
+      "detail": "Create, edit, and delete your Certified records (profile, badges, follows, wallet links, and related data).",
       "permissions": [
         {
           "type": "permission",

lexicons/app/certified/permissions/crud.json

@@ -0,0 +1,30 @@
+{
+  "lexicon": 1,
+  "id": "app.certified.permissions.crud",
+  "defs": {
+    "main": {
+      "type": "permission-set",
+      "description": "Permission set granting create, update, and delete on every Certified (app.certified) record collection.",
+      "title": "Manage your Certified data",
+      "detail": "Create, edit, and delete your Certified records (profile, badges, follows, wallet links, and related data).",
+      "permissions": [
+        {
+          "type": "permission",
+          "resource": "repo",
+          "collection": [
+            "app.certified.actor.organization",
+            "app.certified.actor.profile",
+            "app.certified.badge.award",
+            "app.certified.badge.definition",
+            "app.certified.badge.response",
+            "app.certified.graph.follow",
+            "app.certified.link.evm",
+            "app.certified.location",
+            "app.certified.signature.proof"
+          ],
+          "action": ["create", "update", "delete"]
+        }
+      ]
+    }
+  }
+}

lexicons/org/hypercerts/permissions/crud.json

@@ -0,0 +1,32 @@
+{
+  "lexicon": 1,
+  "id": "org.hypercerts.permissions.crud",
+  "defs": {
+    "main": {
+      "type": "permission-set",
+      "description": "Permission set granting create, update, and delete on every Hypercerts (org.hypercerts) record collection.",
+      "title": "Manage your Hypercerts data",
+      "detail": "Create, edit, and delete your Hypercerts records (impact claims, evaluations, funding, and related data).",
+      "permissions": [
+        {
+          "type": "permission",
+          "resource": "repo",
+          "collection": [
+            "org.hypercerts.claim.activity",
+            "org.hypercerts.claim.contribution",
+            "org.hypercerts.claim.contributorInformation",
+            "org.hypercerts.claim.rights",
+            "org.hypercerts.collection",
+            "org.hypercerts.context.acknowledgement",
+            "org.hypercerts.context.attachment",
+            "org.hypercerts.context.evaluation",
+            "org.hypercerts.context.measurement",
+            "org.hypercerts.funding.receipt",
+            "org.hypercerts.workscope.tag"
+          ],
+          "action": ["create", "update", "delete"]
+        }
+      ]
+    }
+  }
+}

package.json

@@ -42,11 +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",
-    "gen-api": "find ./lexicons -name '*.json' | xargs lex gen-api --yes ./generated && npm run gen-index",
-    "gen-md": "find ./lexicons -name '*.json' | xargs lex gen-md --yes ./lexicons.md",
+    "//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",
     "gen-schemas-md": "node ./scripts/generate-schemas.js",
     "//gen-ts": "UNUSED - use gen-api instead",
-    "gen-ts": "find ./lexicons -name '*.json' | xargs lex gen-ts-obj > generated/DO-NOT-USE-lexicons.ts",
+    "gen-ts": "find ./lexicons -name '*.json' -not -path '*/permissions/*' | xargs lex gen-ts-obj > generated/DO-NOT-USE-lexicons.ts",
     "gen-index": "node ./scripts/generate-exports.js",
     "lex": "lex",
     "test": "vitest run",

scripts/generate-exports.js

@@ -153,28 +153,30 @@ function pathToGeneratedType(filePath) {
   return `./types/${withoutExt}.js`;
 }
 
-/**
- * Read lexicon NSID from JSON file
- */
-function readNsid(filePath) {
-  const fullPath = join(lexiconsDir, filePath);
-  const content = readFileSync(fullPath, "utf-8");
-  const lexicon = JSON.parse(content);
-  return lexicon.lexicon === 1 ? lexicon.id : null;
-}
-
 /**
  * Generate generated/exports.ts content
  */
 function generateIndex() {
-  const jsonFiles = findJsonFiles(lexiconsDir).sort();
-
-  const lexicons = jsonFiles.map((filePath) => ({
+  // Parse each lexicon once, then derive everything from the parsed doc — both
+  // the permission-set check and the NSID — to avoid re-reading the same file.
+  const jsonFiles = findJsonFiles(lexiconsDir)
+    .sort()
+    .map((filePath) => ({
+      filePath,
+      doc: JSON.parse(readFileSync(join(lexiconsDir, filePath), "utf-8")),
+    }))
+    // Permission-set lexicons (lexicons/**/permissions/*.json) are published
+    // as-is but have no TS shape — lex gen-api cannot codegen them, so they are
+    // excluded from `generated/` here just as they are from the gen-* globs in
+    // package.json. The two exclusions must stay aligned.
+    .filter(({ doc }) => doc?.defs?.main?.type !== "permission-set");
+
+  const lexicons = jsonFiles.map(({ filePath, doc }) => ({
     path: filePath,
     importName: pathToImportName(filePath),
     namespace: pathToNamespace(filePath),
     generatedTypePath: pathToGeneratedType(filePath),
-    nsid: readNsid(filePath),
+    nsid: doc.lexicon === 1 ? doc.id : null,
   }));
 
   // Filter out lexicons without NSIDs (should be rare)