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

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

- org.hypercerts.permissions.crud   — CRUD over all org.hypercerts.* records
- app.certified.permissions.crud    — CRUD over all app.certified.* records

Each enumerates every type:"record" collection in its namespace (the spec
forbids wildcards inside a permission set) with action create/update/delete.

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. The full
`npm run check` (gen-api, lint, typecheck, build, test, style) passes.

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

Author: aspiers

.changeset/permission-sets-crud.md

@@ -0,0 +1,11 @@
+---
+"@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.
+
+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`.

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 app.certified.* record collection.",
+      "title": "Full CRUD on Certified record collections",
+      "detail": "Create, update, and delete records in every app.certified.* record collection. Requested as a single include: scope instead of enumerating each repo: scope.",
+      "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 org.hypercerts.* record collection.",
+      "title": "Full CRUD on Hypercerts record collections",
+      "detail": "Create, update, and delete records in every org.hypercerts.* record collection. Requested as a single include: scope instead of enumerating each repo: scope.",
+      "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,