|
| 1 | +--- |
| 2 | +title: Certified Group Service (CGS) |
| 3 | +description: How CGS adds role-based access control to group-governed AT Protocol repositories without modifying the underlying PDS. |
| 4 | +--- |
| 5 | + |
| 6 | +# Certified Group Service (CGS) |
| 7 | + |
| 8 | +In standard AT Protocol, each repository is controlled by a single identity (DID) — there's no built-in way for multiple users to collaboratively manage the same repo with different permission levels. |
| 9 | + |
| 10 | +The [Certified Group Service](https://github.com/hypercerts-org/certified-group-service) (CGS) fills that gap. It's an AT Protocol service that sits between clients and a group's backing PDS, enforcing role-based access control, tracking record authorship, and keeping a full audit log. From the client's perspective, a group looks like any other AT Protocol repository — it just happens to be co-governed. |
| 11 | + |
| 12 | +Certified operates a hosted CGS instance, but CGS is also designed to be **self-hostable per operator** — anyone can run their own instance and point it at whichever PDS backs the group (including, but not limited to, the [Certified-operated PDSs](/reference/certified-services)). |
| 13 | + |
| 14 | +Today, a given CGS deployment points at a single backing PDS (configured via the `GROUP_PDS_URL` environment variable), and every group it registers lives on that PDS. Operators who want to host groups across multiple PDSs currently run multiple CGS instances. This is a current architectural constraint rather than a fundamental one, and may evolve in the future. |
| 15 | + |
| 16 | +## System overview |
| 17 | + |
| 18 | +```text |
| 19 | +Any AT Protocol client |
| 20 | + │ |
| 21 | + │ atproto-proxy: did:plc:GROUP#certified_group |
| 22 | + ▼ |
| 23 | +User's PDS |
| 24 | + │ |
| 25 | + │ Authorization: Bearer <service-auth-jwt> |
| 26 | + │ (signed with user's key, iss=user, aud=group) |
| 27 | + ▼ |
| 28 | +┌──────────────────────────────────┐ |
| 29 | +│ Certified Group Service │ |
| 30 | +│ │ |
| 31 | +│ 1. AuthVerifier (JWT → DID) │ |
| 32 | +│ 2. RbacChecker (DID → role) │ |
| 33 | +│ 3. PDS proxy (forward) │ |
| 34 | +│ 4. AuditLogger (record all) │ |
| 35 | +└──────────────────────────────────┘ |
| 36 | + │ |
| 37 | + ▼ |
| 38 | +Group's backing PDS |
| 39 | +``` |
| 40 | + |
| 41 | +Clients never call CGS directly. Instead they send a normal XRPC request to their own PDS with an `atproto-proxy` header pointing at the group DID and service fragment (`did:plc:GROUP#certified_group`). The user's PDS resolves the group's DID document, finds the `#certified_group` service endpoint, mints a service auth JWT signed with the user's key, and forwards the request to CGS. This is the same proxying mechanism used by Ozone labeling services. |
| 42 | + |
| 43 | +## Integrating from an app |
| 44 | + |
| 45 | +Apps don't call CGS directly. Your backend uses an authenticated `AtpAgent` for the user and sends XRPC requests *to the user's PDS* with an `atproto-proxy` header set to `did:plc:<groupDid>#certified_group`. The PDS handles service auth and forwards the request to CGS on your behalf. See the upstream [integration guide](https://github.com/hypercerts-org/certified-group-service/blob/main/docs/integration-guide.md) for a worked example. |
| 46 | + |
| 47 | +One important gotcha: CGS uses **custom NSIDs** for record operations — `app.certified.group.repo.createRecord`, `putRecord`, `deleteRecord`, `uploadBlob` — instead of the standard `com.atproto.repo.*`. This is deliberate: if your app called `com.atproto.repo.createRecord`, the user's PDS would handle it itself and write to the user's own repo, not proxy it to CGS. The custom NSIDs are unrecognized by the PDS, so it looks them up in the group's DID document and routes them to CGS. Use the custom NSIDs in your proxied calls. |
| 48 | + |
| 49 | +## Authentication |
| 50 | + |
| 51 | +Every request to CGS arrives with `Authorization: Bearer <JWT>`. The `AuthVerifier` runs the following checks: |
| 52 | + |
| 53 | +1. **Signature** — verified against the issuer's DID document via `@atproto/xrpc-server`'s `verifyJwt()`. |
| 54 | +2. **Audience** — the JWT's `aud` must match a group DID registered with this CGS instance. |
| 55 | +3. **Lexicon method** — the JWT's `lxm` must match the requested XRPC method (from an allowlist of record and group-management operations). |
| 56 | +4. **Token lifetime** — `exp - iat` must not exceed the nonce TTL (120 seconds), so that tokens can't outlive the replay-prevention window. |
| 57 | +5. **Nonce (replay prevention)** — the JWT's `jti` is checked against a short-lived nonce cache. If it's been seen before, the request is rejected. |
| 58 | + |
| 59 | +If all checks pass, the handler receives `{ iss: callerDid, aud: groupDid }` and proceeds to authorization. |
| 60 | + |
| 61 | +## Authorization (RBAC) |
| 62 | + |
| 63 | +Roles are strictly hierarchical and compared numerically. A higher level grants every permission of the lower levels. |
| 64 | + |
| 65 | +```text |
| 66 | +member (0) < admin (1) < owner (2) |
| 67 | +``` |
| 68 | + |
| 69 | +### Permission matrix |
| 70 | + |
| 71 | +| Operation | Minimum role | |
| 72 | +|---|---| |
| 73 | +| Create records, upload blobs, edit any record, list members | member | |
| 74 | +| Delete records you authored | member | |
| 75 | +| Delete any member's record | admin | |
| 76 | +| Edit the group's profile | admin | |
| 77 | +| Add / remove members | admin | |
| 78 | +| Query the audit log | admin | |
| 79 | +| Change a member's role | owner | |
| 80 | + |
| 81 | +### Special rules |
| 82 | + |
| 83 | +- **Cannot modify equal or higher roles.** An admin cannot remove another admin; only an owner can. |
| 84 | +- **`member.add` cannot assign `owner`.** New owners must be promoted by an existing owner via `role.set`. |
| 85 | +- **Self-removal always succeeds.** Any member can remove themselves, regardless of role. |
| 86 | +- **Last-owner protection.** The system atomically prevents demoting or removing the only remaining owner. |
| 87 | +- **Authorship is tracked per record.** CGS maintains a `group_record_authors` table so `deleteOwnRecord` (member) can be distinguished from `deleteAnyRecord` (admin). |
| 88 | + |
| 89 | +## PDS proxying and credentials |
| 90 | + |
| 91 | +Once a request is authorized, CGS forwards it to the group's backing PDS using stored credentials: |
| 92 | + |
| 93 | +- **Credential storage.** The group's PDS app password (and, where applicable, the recovery keypair used for PLC operations) is stored encrypted with AES-256-GCM, using a 32-byte master key from the service's `ENCRYPTION_KEY` environment variable. |
| 94 | +- **Agent pool.** An authenticated `AtpAgent` per group is cached in memory; stale sessions are refreshed automatically on `AuthenticationRequired` / `ExpiredToken` errors. |
| 95 | +- **Blob uploads.** `uploadBlob` requests are streamed to the PDS with an enforced `MAX_BLOB_SIZE` limit (checked both upfront via `Content-Length` and incrementally during the stream). |
| 96 | + |
| 97 | +## Audit logging |
| 98 | + |
| 99 | +Every meaningful action — permitted or denied — is written to the per-group `group_audit_log` table. Each entry captures: |
| 100 | + |
| 101 | +- **Who** — the caller's DID (`actor_did`) |
| 102 | +- **What** — the operation name (e.g. `createRecord`, `member.add`) |
| 103 | +- **Where** — collection and rkey, for record-level operations |
| 104 | +- **Result** — `permitted` or `denied` (plus a reason for denials) |
| 105 | +- **Tracing** — the JWT's `jti`, for correlation with auth logs |
| 106 | +- **When** — ISO timestamp |
| 107 | + |
| 108 | +Admins can query the audit log via `app.certified.group.audit.query`. |
| 109 | + |
| 110 | +## Group lifecycle |
| 111 | + |
| 112 | +Groups are created via `app.certified.group.register`, which requires a service auth JWT proving the caller controls the prospective owner DID. During registration, CGS: |
| 113 | + |
| 114 | +1. Creates a new PDS account on the instance's configured backing PDS and receives a new group DID. |
| 115 | +2. Generates a recovery keypair and registers a `#certified_group` service entry in the group's DID document via a PLC operation. |
| 116 | +3. Stores the encrypted app password and recovery key in its own database. |
| 117 | +4. Seeds the caller as the group's first owner. |
| 118 | + |
| 119 | +From then on, the group's DID is co-governed through CGS: owners promote admins, admins manage members, and members interact with the repository subject to the permission matrix above. |
| 120 | + |
| 121 | +## Storage |
| 122 | + |
| 123 | +CGS uses SQLite for all persistence: |
| 124 | + |
| 125 | +- A **global database** holds the group registry (`groups` table) and the nonce cache. |
| 126 | +- Each group gets its **own per-group database**, named by the SHA-256 hash of the group DID. This isolates group data and keeps audit logs per-group. |
| 127 | +- All databases use WAL mode for concurrent read performance. |
| 128 | + |
| 129 | +## Future directions |
| 130 | + |
| 131 | +The current RBAC model — three fixed roles (`member`, `admin`, `owner`) with a hard-coded permission matrix — is intentionally simple. It covers the common case of a small group co-managing a repository, but it is a starting point rather than an endpoint. Directions being explored as groups' governance needs mature: |
| 132 | + |
| 133 | +- **Customizable roles.** Let each group define its own roles and permissions instead of relying on a fixed three-tier hierarchy. |
| 134 | +- **Finer-grained permissions.** Scope permissions per collection or record type — for example, a role that can only create records in one lexicon, or only edit the group profile. |
| 135 | +- **Group-level governance.** Move beyond unilateral admin/owner actions toward proposals, voting, or quorum-based decisions for sensitive operations. |
| 136 | +- **Time-bound and delegated roles.** Temporary elevations — e.g. an admin grants another member `admin` for 24 hours, after which the role automatically reverts. |
| 137 | +- **Credential-based membership.** Derive membership and roles from external signals (verifiable credentials, badges, tokens) rather than only manual `member.add` calls. |
| 138 | +- **Multiple backing PDSs per instance.** Today, one CGS deployment is bound to a single backing PDS. Supporting multiple PDSs per instance (or per group) would let a single deployment host groups across different PDS providers. |
| 139 | + |
| 140 | +None of the above are committed features; they're possibilities being shaped by user and developer needs and feedback. |
| 141 | + |
| 142 | +## Further reading |
| 143 | + |
| 144 | +- [CGS repository](https://github.com/hypercerts-org/certified-group-service) |
| 145 | +- [Architecture doc](https://github.com/hypercerts-org/certified-group-service/blob/main/docs/architecture.md) — full data model, startup sequence, and implementation details |
| 146 | +- [Integration guide](https://github.com/hypercerts-org/certified-group-service/blob/main/docs/integration-guide.md) |
| 147 | +- [API reference](https://github.com/hypercerts-org/certified-group-service/blob/main/docs/api-reference.md) |
| 148 | +- [Deployment guide](https://github.com/hypercerts-org/certified-group-service/blob/main/docs/deployment.md) — for running your own CGS instance |
0 commit comments