Status: confirmed with the Phase 1 team on 9 October 2026, against auth branch migration-phase1.
Relation to the RFC: this file records how the IdP actually behaves where it is more precise than, or differs from, the RFC. Where the two disagree, this file and the IdP code win. Each difference is marked (differs from RFC).
The executable form of this contract is the @polinetwork/auth-kit/contract entry point (constants, schemas, producer types) and the fixtures in fixtures/, which ship as @polinetwork/auth-kit/fixtures/*. idp-adoption.md describes how the IdP can import both.
Fixed in the IdP code. Changing any of these needs a coordinated IdP and SDK change. They are exported from src/contract/.
| Item | Value |
|---|---|
| Snapshot endpoint | GET /api/internal/access-snapshot |
| Snapshot schema | polinetwork.access-snapshot/v1 |
| Projection name | backend (the only projection today) |
| ETag format | "sha256-<64 hex>", treated as opaque by the SDK |
| Event URI | https://schemas.polinetwork.org/events/access-changed |
| Snapshot scope | idp:access:read |
| Subject-type claim | pn_subject_type: user or client |
| Signing algorithm | EdDSA (Ed25519) |
| Access-token TTLs | 3600 s for the backend resource, 300 s for the internal resource |
| Event sender timeout | 8 s; only an exact 202 counts as delivered |
Configuration, from env or the deployment: the IdP base URL (BETTER_AUTH_URL), both resource identifiers, the backend client ID, the event receiver URL, hostnames and the poll interval. idpEndpoints() derives the rest:
| Derived value | From |
|---|---|
| Issuer | <public URL>/api/auth |
| JWKS | <public or internal URL>/api/auth/jwks |
| Token endpoint (request target) | <public or internal URL>/api/auth/oauth2/token |
Client-assertion aud |
<public URL>/api/auth/oauth2/token, always public (RFC §12) |
- Permissions are fully expanded. Roles are resolved up through their parents and permissions down through their implications, transitively, in the IdP. The SDK only ever does a key lookup and repeats no role logic.
- Master Admin is written out, never
*. Its entry lists every permission key the projection carries. Break-glass admins getvalidUntil: null; members of the Entra admin group get that group'sobservedAt+ 1 h. - Validity per key: an implied key inherits the validity of the path that granted it. When several paths grant a key, the latest expiry wins and
nullbeats any date. - The
backendprojection carries every permission except the IdP's ownidp:*ones, which never appear, even when implied by a key that does. roleslists the effective roles under the same expiry rules: every granted role plus every role it inherits from through its parents. A subject is still included only for its permissions. The SDK reads roles as given (hasRole,roles) and repeats no hierarchy logic.catalognames every role and every projected permission ({ key, name }, sorted by key), for pickers. It is display data only: a missing or malformedcataloggives two empty lists, a malformedrolesorpermissionslist empties only that list, and the snapshot is still accepted.- IdPs before roles were projected send neither
rolesnorcatalog. Those snapshots, including persisted ones, still parse, with no roles and an empty catalog. - Absent means no permissions. People without a projected permission are omitted, including people who linked Telegram. An unknown
subor Telegram ID is not an error. telegramIdmay benullfor someone who linked Telegram, when the link is ambiguous (one person with several IDs, or one ID shared by several people). Duplicates therefore cannot appear; the SDK still rejects them as a backstop.telegramIdis a decimal string matching^[1-9]\d*$.entraObjectIdis the Entra object ID (oid) of the PoliNetwork Microsoft 365 account the subject signs in with, the one that provessocioanddirettivo. Use it to find the person's own records keyed by their Microsoft 365 account. LiketelegramId, it isnullwhen the subject has no Microsoft 365 sign-in or the link is ambiguous (one person with several Microsoft 365 accounts, or one account shared by several people), so it never appears twice. It stays while the account is linked, whatever the group membership. IdPs before it was projected omit it, and the SDK reads that asnull.- Until Phase 2 creates the
tg:*permissions, the production snapshot is nearly empty. Test against a local IdP with seeded permissions.
- Sources are an open set. Possible keys today:
rbac,entra:soci,entra:direttivo,entra:admins,polimi-email.entra:direttivoandentra:adminsappear only when their groups are configured. The parser accepts missing and unknown keys. - The only error code is
graph_unavailable(the RFC example saysgraph_timeout). The parser accepts any string. - Timestamps carry milliseconds (
…T11:14:31.000Z). The parser accepts any ISO 8601 precision and offset. builtAtcan be old on a healthy IdP. When nothing changed, the IdP returns the stored body unchanged, includingbuiltAtand therbac/polimi-emailobservedAt. Without Entra configured this can be days old.generationand the ETag change on almost every pull when Entra is configured, because each observation movesobservedAtand the derivedvalidUntilvalues.generationis informational only.
| Status | Meaning | SDK reaction |
|---|---|---|
200 |
Body follows | Validate, swap in, persist, set lastSyncAt |
304 |
Body identical to the sent ETag | Set lastSyncAt |
401 |
Bad token, scope or audience ({ "error": … }) |
Drop the cached token, fetch a new one, retry once |
403 |
Valid token from a client without a projection | Configuration alert; no fast retry |
503 |
Endpoint not configured, or the build failed | Back off; keep the last good snapshot |
If-None-Match: *always returns304. The SDK sends only an ETag the IdP returned.- The snapshot-pull token must carry exactly one
resource. The IdP requiresaudto be a string equal to the internal resource.
| Field | Value |
|---|---|
| Header | typ: secevent+jwt, alg: EdDSA, kid of the IdP's current key |
iss |
<public URL>/api/auth |
aud |
The backend resource identifier |
iat, exp |
exp = iat + 60 s; every attempt is signed anew (differs from RFC) |
jti |
access-<lowest outbox id in the batch>, reused on retries (differs from RFC) |
events |
{ "<event URI>": { "projection": "backend" } }; no sub |
| Transport | POST, Content-Type: application/secevent+jwt, the bare JWT as body |
- Never deduplicate by
jti. A retry reuses it and may also cover changes made after the first attempt. Every valid event means "pull now". - Duplicates are expected. After a timeout or a crashed sender, the same
jtiarrives again after up to 30 s. - Retries back off from 2 s up to 60 s after any non-
202answer or no answer within 8 s. - Receiver budget: about 6 s. A pull triggered by an event usually reads Graph again (the IdP reuses observations only for 15 s, and reads time out after 5 s). The receiver answers
202after the pull completes, or503past the budget while the pull keeps running.
- Rotation: every 7 days, with old keys still published for 30 days.
KEYS_MAX_AGE = 24 his well inside that. - A new key is used as soon as it is created (differs from RFC §6.5, step 2). better-auth creates the key on demand and signs with it immediately. The key is published at the same moment, because the JWKS is served from the database, but a client cannot have fetched it in advance.
- SDK rule for an unknown
kid: refetch immediately when the token'siatis later than the last fetch (one fetch at a time, with a short minimum gap); otherwise at most once per 30 s. An unknownkidstill fails closed after the fetch.
MAX_STALEis measured only fromlastSyncAt, the time of the last200or304.builtAtandobservedAtare never used for freshness (§2.2).- Per-key
validUntilis enforced locally at every check, whatever the sync state.
- Event signing after key expiry (unverified). The dispatcher passes
signingAlgorithm: "EdDSA"tosignJWT. In better-auth 1.7.2 an explicit algorithm makessignJWTthrow instead of creating a key when the current one has expired (plugins/jwt/sign.mjs:57-58). If so, events fail after each weekly expiry until another issuance creates the key. Polling covers the gap. - RFC update. §5.3 and §5.6 should take the differences marked above.