feat: permission sets for Hypercerts & Certified data

[aspiers]

Summary

Adds permission sets for the org.hypercerts.*, org.hyperboards.*, and app.certified.* record collections — both the design and the implementation.

A permission set lets any AT Protocol app request a whole bundle of repo: scopes with one 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.

One set per namespace, by spec mandate

There are three separate sets — not one combined set — 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, org.hyperboards, and app.certified are different namespace authorities (hypercerts.org, hyperboards.org, certified.app), so a single set legally cannot span them. An app needing more than one requests each include: scope.

NSID shape (single segment under the namespace root)

The same authority rule constrains the set's own NSID: NSID.authority is the reversed domain of all-but-the-last segment, so the set must be a single leaf directly under the namespace root — org.hypercerts.authWrite, not org.hypercerts.permissions.crud (whose authority permissions.hypercerts.org would fail to parent org.hypercerts.claim.*, making IncludeScope.toScopes silently return []). This matches Bluesky's own published sets (app.bsky.authViewAll, app.bsky.authCreatePosts, app.bsky.authDeleteContent, app.bsky.authFullApp — single segment, auth-prefixed leaf) and the spec's com.example.authFull examples.

Contents

Design — docs/design/permission-sets.md (new docs/design/ dir): holistic, covering the sets as general AT Protocol artifacts usable by direct OAuth clients, CGS-via-OAuth, and CGS API keys — all consumers of the same published Lexicon source of truth.

Implementation — three permission-set lexicons:

Lexicon → NSID	Grants write (create/update/delete) on
lexicons/org/hypercerts/authWrite.json → org.hypercerts.authWrite	all org.hypercerts.* record collections (11)
lexicons/org/hyperboards/authWrite.json → org.hyperboards.authWrite	all org.hyperboards.* record collections (2)
lexicons/app/certified/authWrite.json → app.certified.authWrite	all app.certified.* record collections (9)

Each enumerates every type: "record" collection in its namespace with action: [create, update, delete], and expands to a single combined repo: scope.

Process docs — AGENTS.md's "Adding / modifying a lexicon" checklist gains a step: when a new org.hypercerts.* / org.hyperboards.* / app.certified.* record lexicon is added (or removed), update its namespace's permission set to match, since the enumerated collection list is both the grant and its boundary.

Design rules followed (spec-cited in the doc)

• Own-namespace authority → one set per namespace, single-segment NSID under the root (above).
• No wildcards inside a set → collections enumerated (the list is the grant + boundary; a Maintenance section flags keeping it in sync).
• repo: scopes carry no aud → requested without ?aud=. No read action exists in the scope grammar (records are world-readable), so these are write sets; title/detail are authorization-dialog consent copy.

Tooling note

permission-set is a lexicon primitive lex gen-api cannot codegen (it has no TS shape; verified both @atproto/lex-cli@0.9.6 and 0.10.0 throw). These sets need no TS shape — they are the source of truth published to AT Protocol. So they are:

• excluded from the lex codegen invocations via scripts/run-lex-codegen.js — a Node runner that builds the lexicon file list (filtering out defs.main.type === "permission-set") and spawns lex <subcommand> … <files> with it as argv, forwarding lex's exit code, and
• skipped by scripts/generate-exports.js (same content check),

the single content-based exclusion shared by both, so it doesn't break when set files move. They still ship as raw lexicon JSON and appear in SCHEMAS.md. Full npm run check passes.

(The runner replaced an earlier shell pipeline: lex … $(node …) swallowed a producer failure, and the node … | xargs form needed set -o pipefail, which the dash that npm runs scripts with on GitHub's Ubuntu runners rejects. A single Node process gives one authoritative exit code with no shell word-splitting or pipefail dependency.)

Rebased onto #219

PR #219 (signature support, HYPER-181) has since merged, adding the app.certified.signature.proof record lexicon. This branch is rebased onto it and app.certified.signature.proof is now included in app.certified.authWrite (9 collections), so the set covers every app.certified.* record on main. The earlier "pending follow-up" note has been dropped from the design doc's Maintenance section.

Notes

• Suggested NSIDs (*.authWrite) follow Bluesky's auth* convention; rename freely.
• Includes a minor changeset.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added three new permission-set lexicons (Hypercerts, Hyperboards, and Certified), enabling scoped write access (create/update/delete) per namespace via include:<nsid> OAuth scopes.
• Documentation
  • Added a permission-sets design guide, expanded setup/maintenance steps to keep permissions aligned with record collections (no wildcards), and updated schema documentation to render permission-set entries.
• Chores
  • Updated lexicon generation/tooling so permission-set lexicons are consistently excluded from code generation while still being correctly reflected in generated schema output.

[changeset-bot]

🦋 Changeset detected

Latest commit: 733f555

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/lexicon	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds three namespace-scoped permission-set lexicons, documents how to request and maintain them, and updates code generation so permission-set JSON is excluded from generated outputs while still shipping as raw lexicon files.

Changes

Permission set definitions

Layer / File(s)	Summary
Permission-set lexicon definitions and schemas SCHEMAS.md, lexicons/org/hypercerts/authWrite.json, lexicons/org/hyperboards/authWrite.json, lexicons/app/certified/authWrite.json, .changeset/permission-sets-crud.md	Adds three authWrite permission-set lexicons and matching schema entries, plus a changeset describing the new scope bundles and collection enumeration rules.

Documentation and workflow updates

Layer / File(s)	Summary
Permission-set design and workflow docs docs/design/permission-sets.md, .agents/skills/building-with-hypercerts-lexicons/SKILL.md, AGENTS.md	Adds design and workflow documentation for include:<nsid> permission sets, namespace and collection constraints, resolution behavior, and maintenance steps for keeping them aligned with record lexicons.

Code generation and export filtering

Layer / File(s)	Summary
Lex codegen runner and export filtering package.json, scripts/run-lex-codegen.js, scripts/generate-exports.js, scripts/generate-schemas.js	Switches lex codegen scripts to a Node runner that filters permission-set lexicons, and updates export generation and schema rendering to handle permission-set lexicon JSON directly.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• hypercerts-org/hypercerts-lexicon#70: Updates the AGENTS.md changesets workflow that this PR now references in its regeneration steps.
• hypercerts-org/hypercerts-lexicon#195: Introduced the downstream AI skill guide that this PR extends with permission-set documentation.
• hypercerts-org/hypercerts-lexicon#97: Added the schema-generation path that this PR extends to render permission-set lexicons.
• Suggested reviewers: s-adamantine, holkexyz

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the addition of permission sets, though it omits Hyperboards from the full scope.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Lexicon Documentation Sync	✅ Passed	New permission-set lexicons are added in JSON and mirrored in SCHEMAS.md; README.md and ERD.puml don’t reference these IDs, so no sync issue.
Lexicons Styleguide Compliance	✅ Passed	PASS: The new lexicon files use the expected auth-prefixed NSIDs and permission-set type; I found no undocumented styleguide deviations.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/permission-sets-design

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds a new design document describing two AT Protocol permission sets intended to bundle repo-scope permissions for the org.hypercerts.* and app.certified.* record-collection namespaces, so OAuth clients (and CGS) can request a single include:<nsid> scope instead of enumerating per-collection repo: scopes.

Changes:

• Introduces docs/design/permission-sets.md documenting proposed permission-set NSIDs and their expanded scopes.
• Enumerates the targeted record collections for each namespace and records design constraints (namespace authority, no wildcards, no aud for repo:).
• Describes publication/resolution flow and CGS consumption patterns.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Ashex]

Approved pending testing per our discussion

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

scripts/generate-schemas.js (1)

275-293: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Only handles repo-type permissions; rpc permissions would render incomplete.

Per the AT Protocol permission spec, a permission's resource field can be "rpc" (with lxm/aud/inheritAud fields) in addition to "repo" (collection/action). This function only renders collection/action, so an rpc permission would print just **Resource:** \rpc`with no endpoint/audience detail — not incorrect for the three lexicons in this PR (allrepo-only), but incomplete if a future permission set in this repo adds rpc` permissions.

♻️ Optional: extend to cover `rpc` permissions

   for (const permission of permissions) {
     const collections = (permission.collection || [])
       .map((c) => `\`${c}\``)
       .join(", ");
     const actions = (permission.action || []).map((a) => `\`${a}\``).join(", ");
     output.push(`**Resource:** \`${permission.resource}\``, "");
     if (collections) output.push(`**Collections:** ${collections}`, "");
     if (actions) output.push(`**Actions:** ${actions}`, "");
+    const lxm = (permission.lxm || []).map((l) => `\`${l}\``).join(", ");
+    if (lxm) output.push(`**LXM:** ${lxm}`, "");
+    if (permission.aud) output.push(`**Audience:** \`${permission.aud}\``, "");
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/generate-schemas.js` around lines 275 - 293,
generatePermissionSetSection only formats repo-style permissions, so rpc
permissions would be incomplete. Update this helper to branch on
permission.resource and, for rpc entries, render the rpc-specific fields such as
lxm, aud, and inheritAud alongside the resource label; keep the existing
collection/action rendering for repo permissions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/design/permission-sets.md`:
- Around line 85-87: The blockquote in the permission-sets documentation is
broken by an empty separator line, which triggers MD028. Update the quoted
section so the gap is either removed or the separator line is also prefixed with
the blockquote marker, keeping the entire paragraph sequence within the same
blockquote near the “Naming” text.

---

Nitpick comments:
In `@scripts/generate-schemas.js`:
- Around line 275-293: generatePermissionSetSection only formats repo-style
permissions, so rpc permissions would be incomplete. Update this helper to
branch on permission.resource and, for rpc entries, render the rpc-specific
fields such as lxm, aud, and inheritAud alongside the resource label; keep the
existing collection/action rendering for repo permissions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3777a009-7424-4d96-8e04-d0a98e383519

📥 Commits

Reviewing files that changed from the base of the PR and between 2f281d4 and cd08e55.

📒 Files selected for processing (12)

• .agents/skills/building-with-hypercerts-lexicons/SKILL.md
• .changeset/permission-sets-crud.md
• AGENTS.md
• SCHEMAS.md
• docs/design/permission-sets.md
• lexicons/app/certified/authWrite.json
• lexicons/org/hyperboards/authWrite.json
• lexicons/org/hypercerts/authWrite.json
• package.json
• scripts/generate-exports.js
• scripts/generate-schemas.js
• scripts/run-lex-codegen.js

✅ Files skipped from review due to trivial changes (1)

• lexicons/app/certified/authWrite.json

🚧 Files skipped from review as they are similar to previous changes (6)

• lexicons/org/hyperboards/authWrite.json
• lexicons/org/hypercerts/authWrite.json
• package.json
• scripts/generate-exports.js
• SCHEMAS.md
• AGENTS.md

[aspiers]

Tested in hypercerts-org/ePDS#188 and it looks good:

[aspiers]

(comment generated by Claude Code)

Re: CodeRabbit review-summary nitpick — "generatePermissionSetSection only handles repo-type permissions; rpc permissions would render incomplete" (scripts/generate-schemas.js ~275-293):

Stale — no action taken. There is no generatePermissionSetSection (or any permission-rendering code) in scripts/generate-schemas.js anymore; grep -rn "generatePermissionSetSection|permission.resource|\*\*Collections:\*\*" scripts/ returns nothing. Permission-set lexicons are excluded from schema/codegen output entirely (by the main.type === "permission-set" content check), so there is no repo-vs-rpc rendering path to extend. The nitpick refers to code that is not present in this PR.

[aspiers]

(comment generated by Claude Code)

Correction to my earlier comment (above): I wrongly called this nitpick "stale." I searched a stale local checkout that was behind this PR's HEAD and lacked commit cd08e55, so I did not see generatePermissionSetSection. It does exist and the nitpick is valid.

Fixed in 733f555. generatePermissionSetSection now renders rpc-permission fields (**LXM:** / **Audience:** / **Inherit audience:**) alongside the existing repo collection/action rendering, so an rpc permission no longer collapses to a bare **Resource:** +""+rpc+""+`. No change to current SCHEMAS.md output — all three published sets are repo-only — but future rpc permissions now render completely.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[aspiers]

This is already published and working - thought we'd already merged this -> merging.