+22

docs/05-auth.md

Reviewed

··· 190 190 191 191 Public requests skip all verification middleware — no JWT parsing, no DID-doc fetch. Fast path. 192 192 193 193 + ## Trust assumptions 194 194 + 195 195 + Two trust assumptions in the binding layer cannot be closed at the Contrail layer alone. They are listed here so operators picking a binding strategy or onboarding flow can size them against their own threat model. 196 196 + 197 197 + ### DID-doc binding path 198 198 + 199 199 + The record host can resolve a space's authority from three sources (see [Spaces § Discovery](./06-spaces.md#discovery--binding-resolution)): 200 200 + 201 201 + - **Local enrollment** — the host's own `record_host_enrollments` table, written via `recordHost.enroll`. Owner-signed; the host has full control over what's stored. 202 202 + - **PDS record** — read from the owner's PDS at the space URI. 203 203 + - **DID-doc service entry** — read from `service[id="#atproto_space_authority"]` on the owner's DID doc. 204 204 + 205 205 + The DID-doc path inherits PLC's authorization model: any rotation key on the owner's account can submit an update op rewriting the service entry. There is no per-entry signature or "this entry can only be edited by key X" constraint at the PLC layer. 206 206 + 207 207 + If the integrity of the space-authority binding needs to exceed what any one of the owner's rotation keys can already do, configure the host to resolve via local enrollment instead, or wait for an upstream signed-binding mechanism. Tracked upstream as [flo-bit/contrail#38](https://github.com/flo-bit/contrail/issues/38). 208 208 + 209 209 + ### Contrail-held PDS app password 210 210 + 211 211 + Deployments running `community.provision` or `community.adopt` necessarily hold an ATProto app password for the user-owned PDS account so Contrail can write on the community's behalf. ATProto app passwords are unscoped at the PDS layer — they can write any record to the repo, including the `tools.atmo.space.declaration` record (or its embedded equivalent on a space-type record) that drives binding decisions in `createPdsBindingResolver`. 212 212 + 213 213 + This is an intentional consequence of the managed-community model, not a bug. Operators should treat stored app passwords with the same care as rotation keys, and reach for scoped app passwords (when ATProto adds them) or signed binding records to tighten the model further. Tracked upstream as [flo-bit/contrail#39](https://github.com/flo-bit/contrail/issues/39). 214 214 + 193 215 ## How the pieces fit 194 216 195 217 A typical flow for a third-party app acting as a user in a space:

+9

docs/10-deployment-shapes.md

Reviewed

··· 192 192 193 193 When in doubt, all-in-one. Splitting is for when you have a real operational reason to separate the two — different teams running them, different latency profiles, different scaling targets, different governance. 194 194 195 195 + ## Known trust assumptions 196 196 + 197 197 + Two assumptions in the binding layer cannot be closed at the Contrail layer alone, and which one applies depends on the shape you pick: 198 198 + 199 199 + - Deployments wiring `createDidDocBindingResolver` inherit PLC's rotation-key authorization model for the `#atproto_space_authority` service entry. Tracked as [flo-bit/contrail#38](https://github.com/flo-bit/contrail/issues/38). 200 200 + - Deployments running `community.provision` or `community.adopt` hold an unscoped ATProto app password for each provisioned PDS account. Tracked as [flo-bit/contrail#39](https://github.com/flo-bit/contrail/issues/39). 201 201 + 202 202 + See [Auth § Trust assumptions](./05-auth.md#trust-assumptions) for the constraints in detail and what binding source to prefer when those assumptions don't fit your threat model. 203 203 + 195 204 ## What's not here 196 205 197 206 - **Authority migration** — moving a space's authority from DID A to DID B. The architecture supports it (re-enroll on the host with the new authority binding) but no helper API yet.

+1 -10

packages/contrail-appview/src/core/spaces/router.ts

Reviewed

··· 9 9 import { 10 10 buildVerifier, 11 11 createBindingCredentialVerifier, 12 12 - createCompositeBindingResolver, 13 12 createEnrollmentBindingResolver, 14 14 - createLocalBindingResolver, 15 13 createLocalKeyResolver, 16 14 createServiceAuthMiddleware, 17 15 } from "@atmo-dev/contrail-base"; ··· 71 69 ); 72 70 73 71 if (spacesConfig.recordHost) { 74 74 - // Default in-process verifier: enrollment is the canonical binding 75 75 - // source; Local-binding is a fallback for spaces created but not yet 76 76 - // enrolled. Caller overrides via `options.credentialVerifier` to 77 77 - // accept external authorities. 78 72 const credentialVerifier = 79 73 options.credentialVerifier ?? 80 74 (authorityConfig.signing 81 75 ? createBindingCredentialVerifier({ 82 82 - bindings: createCompositeBindingResolver([ 83 83 - createEnrollmentBindingResolver({ recordHost: adapter }), 84 84 - createLocalBindingResolver({ authorityDid: authorityConfig.serviceDid }), 85 85 - ]), 76 76 + bindings: createEnrollmentBindingResolver({ recordHost: adapter }), 86 77 keys: createLocalKeyResolver({ 87 78 authorityDid: authorityConfig.serviceDid, 88 79 publicKey: authorityConfig.signing.publicKey,

+9 -3

packages/contrail-base/src/spaces/binding.ts

Reviewed

··· 141 141 } 142 142 if (!res.ok) return null; 143 143 const body = (await res.json().catch(() => null)) as 144 144 - | { value?: { authority?: unknown } } 144 144 + | { value?: { $type?: unknown; authority?: unknown; createdAt?: unknown } } 145 145 | null; 146 146 - const authority = body?.value?.authority; 147 147 - return typeof authority === "string" && authority.startsWith("did:") ? authority : null; 146 146 + const value = body?.value; 147 147 + if (!value) return null; 148 148 + if (value.$type !== parts.type) return null; 149 149 + if (typeof value.createdAt !== "string") return null; 150 150 + const authority = value.authority; 151 151 + if (typeof authority !== "string") return null; 152 152 + if (!/^did:(plc|web):[a-zA-Z0-9._:%-]+(#[a-zA-Z0-9._-]+)?$/.test(authority)) return null; 153 153 + return authority; 148 154 }, 149 155 }; 150 156 }

+2 -4

packages/contrail-record-host/src/routes.ts

Reviewed

··· 107 107 if (!parts) { 108 108 return c.json({ error: "InvalidRequest", reason: "malformed-uri" }, 400); 109 109 } 110 110 - const callerIsOwner = sa.issuer === parts.ownerDid; 111 111 - const callerIsAuthority = sa.issuer === body.authority; 112 112 - if (!callerIsOwner && !callerIsAuthority) { 110 110 + if (sa.issuer !== parts.ownerDid) { 113 111 return c.json( 114 114 - { error: "Forbidden", reason: "not-owner-or-authority" }, 112 112 + { error: "Forbidden", reason: "not-owner" }, 115 113 403 116 114 ); 117 115 }

+66

packages/contrail/tests/spaces-binding.test.ts

Reviewed

··· 158 158 }); 159 159 expect(await r.resolveAuthority(SPACE_URI)).toBeNull(); 160 160 }); 161 161 + 162 162 + it("returns null when the record's $type doesn't match the URI's type", async () => { 163 163 + const fetch = mockFetch( 164 164 + new Map([ 165 165 + [ 166 166 + "https://pds.test/xrpc/com.atproto.repo.getRecord", 167 167 + { 168 168 + value: { 169 169 + $type: "com.attacker.fake.type", 170 170 + authority: "did:web:authority.example", 171 171 + createdAt: "2026-04-30T00:00:00Z", 172 172 + }, 173 173 + }, 174 174 + ], 175 175 + ]) 176 176 + ); 177 177 + const r = createPdsBindingResolver({ 178 178 + resolver: mockResolver({ pdsEndpoint: "https://pds.test" }), 179 179 + fetch, 180 180 + }); 181 181 + expect(await r.resolveAuthority(SPACE_URI)).toBeNull(); 182 182 + }); 183 183 + 184 184 + it("returns null when createdAt is missing or non-string", async () => { 185 185 + const fetch = mockFetch( 186 186 + new Map([ 187 187 + [ 188 188 + "https://pds.test/xrpc/com.atproto.repo.getRecord", 189 189 + { 190 190 + value: { 191 191 + $type: "com.example.event.space", 192 192 + authority: "did:web:authority.example", 193 193 + // createdAt deliberately omitted 194 194 + }, 195 195 + }, 196 196 + ], 197 197 + ]) 198 198 + ); 199 199 + const r = createPdsBindingResolver({ 200 200 + resolver: mockResolver({ pdsEndpoint: "https://pds.test" }), 201 201 + fetch, 202 202 + }); 203 203 + expect(await r.resolveAuthority(SPACE_URI)).toBeNull(); 204 204 + }); 205 205 + 206 206 + it("returns null when authority isn't a well-formed DID", async () => { 207 207 + const fetch = mockFetch( 208 208 + new Map([ 209 209 + [ 210 210 + "https://pds.test/xrpc/com.atproto.repo.getRecord", 211 211 + { 212 212 + value: { 213 213 + $type: "com.example.event.space", 214 214 + authority: "did:fake!!://garbage", 215 215 + createdAt: "2026-04-30T00:00:00Z", 216 216 + }, 217 217 + }, 218 218 + ], 219 219 + ]) 220 220 + ); 221 221 + const r = createPdsBindingResolver({ 222 222 + resolver: mockResolver({ pdsEndpoint: "https://pds.test" }), 223 223 + fetch, 224 224 + }); 225 225 + expect(await r.resolveAuthority(SPACE_URI)).toBeNull(); 226 226 + }); 161 227 }); 162 228 163 229 describe("BindingResolver — DID-doc service entry", () => {

+39 -7

packages/contrail/tests/spaces-enrollment.test.ts

Reviewed

··· 127 127 expect(((await reenroll.json()) as any).ok).toBe(true); 128 128 }); 129 129 130 130 - it("non-owner / non-authority callers cannot enroll", async () => { 130 130 + it("non-owner callers cannot enroll", async () => { 131 131 const app = await makeApp(); 132 132 const create = await call(app, "POST", "/xrpc/test.enroll.space.createSpace", ALICE, {}); 133 133 const uri = ((await create.json()) as any).space.uri; ··· 137 137 authority: SERVICE_DID, 138 138 }); 139 139 expect(res.status).toBe(403); 140 140 - expect((await res.json()).reason).toBe("not-owner-or-authority"); 140 140 + expect((await res.json()).reason).toBe("not-owner"); 141 141 }); 142 142 }); 143 143 ··· 369 369 expect((await list.json()).reason).toBe("not-enrolled"); 370 370 }); 371 371 372 372 - it("the declared authority can enroll a space without the owner's involvement", async () => { 373 373 - // Scenario: the authority service ('Contrail' in our naming) is a 374 374 - // separate DID and acts on behalf of an owner. The authority can enroll 375 375 - // because phase 5 accepts either owner-or-authority. 372 372 + it("a third party cannot enroll a space by claiming to be the authority", async () => { 373 373 + // Regression: the enroll handler used to accept either owner-signed 374 374 + // OR authority-self-attested calls. That let any DID claim "I am the 375 375 + // authority for ats://<victim>/..." and rebind the space. 376 376 const authorityDb = createSqliteDatabase(":memory:"); 377 377 const hostDb = createSqliteDatabase(":memory:"); 378 378 const cfg: ContrailConfig = { ··· 392 392 const create = await call(authorityApp, "POST", "/xrpc/test.split.space.createSpace", ALICE, {}); 393 393 const uri = ((await create.json()) as any).space.uri; 394 394 395 395 - // Authority service identifies itself via the JWT issuer matching its DID. 395 395 + // SERVICE_DID self-attests as the authority for Alice's space. 396 396 + // Must be rejected — only the owner can enroll. 396 397 const enroll = await call(hostApp, "POST", "/xrpc/test.split.recordHost.enroll", SERVICE_DID, { 397 398 spaceUri: uri, 398 399 authority: SERVICE_DID, 399 400 }); 401 401 + expect(enroll.status).toBe(403); 402 402 + expect((await enroll.json()).reason).toBe("not-owner"); 403 403 + }); 404 404 + 405 405 + it("the owner can enroll their space designating a separate authority", async () => { 406 406 + // Positive: the owner-signed path lets Alice point her space at the 407 407 + // configured authority service (the canonical split-deployment flow). 408 408 + const authorityDb = createSqliteDatabase(":memory:"); 409 409 + const hostDb = createSqliteDatabase(":memory:"); 410 410 + const cfg: ContrailConfig = { 411 411 + namespace: "test.split", 412 412 + collections: { message: { collection: "app.event.message" } }, 413 413 + spaces: { 414 414 + authority: { type: "tools.atmo.event.space", serviceDid: SERVICE_DID, signing: SIGNING }, 415 415 + recordHost: {}, 416 416 + }, 417 417 + }; 418 418 + const resolved = resolveConfig(cfg); 419 419 + await initSchema(authorityDb, resolved); 420 420 + await initSchema(hostDb, resolved); 421 421 + 422 422 + const authorityApp = buildAuthorityApp(authorityDb); 423 423 + const hostApp = buildRecordHostApp(hostDb); 424 424 + const create = await call(authorityApp, "POST", "/xrpc/test.split.space.createSpace", ALICE, {}); 425 425 + const uri = ((await create.json()) as any).space.uri; 426 426 + 427 427 + const enroll = await call(hostApp, "POST", "/xrpc/test.split.recordHost.enroll", ALICE, { 428 428 + spaceUri: uri, 429 429 + authority: SERVICE_DID, 430 430 + }); 400 431 expect(enroll.status).toBe(200); 432 432 + expect(((await enroll.json()) as any).ok).toBe(true); 401 433 }); 402 434 });