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. They do
appear in SCHEMAS.md. 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.

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

Author: aspiers

.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`.

SCHEMAS.md

@@ -289,6 +289,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.
@@ -522,6 +528,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.
+
+---
+
 ## Type Definitions
 
 Common type definitions used across all protocols.

docs/design/permission-sets.md

@@ -56,18 +56,27 @@ 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 set titles say "write" to
+> avoid implying a 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 +93,7 @@ Enumerates every `type: "record"` collection under `org.hypercerts.*`:
   "defs": {
     "main": {
       "type": "permission-set",
-      "title": "Full CRUD on Hypercerts record collections",
+      "title": "Full write access (create, update, delete) on Hypercerts record collections",
       "permissions": [
         {
           "type": "permission",
@@ -121,7 +130,7 @@ Enumerates every `type: "record"` collection under `app.certified.*`:
   "defs": {
     "main": {
       "type": "permission-set",
-      "title": "Full CRUD on Certified record collections",
+      "title": "Full write access (create, update, delete) on Certified record collections",
       "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

@@ -163,11 +163,24 @@ function readNsid(filePath) {
   return lexicon.lexicon === 1 ? lexicon.id : null;
 }
 
+/**
+ * Is this lexicon a permission-set? Permission sets are published as-is but
+ * have no generated TypeScript type (lex gen-api cannot process them), so they
+ * are excluded from the generated exports.
+ */
+function isPermissionSet(filePath) {
+  const fullPath = join(lexiconsDir, filePath);
+  const lexicon = JSON.parse(readFileSync(fullPath, "utf-8"));
+  return lexicon?.defs?.main?.type === "permission-set";
+}
+
 /**
  * Generate generated/exports.ts content
  */
 function generateIndex() {
-  const jsonFiles = findJsonFiles(lexiconsDir).sort();
+  const jsonFiles = findJsonFiles(lexiconsDir)
+    .filter((filePath) => !isPermissionSet(filePath))
+    .sort();
 
   const lexicons = jsonFiles.map((filePath) => ({
     path: filePath,