@happyvertical/smrt-users 0.55.18 → 0.55.19

package/README.md

@@ -1355,3 +1355,50 @@ against the new constraint. Apply the remaining application schema migrations,
 run `smrt doctor --db` / `db:status --parity`, deploy the new version to every
 writer, then resume traffic. Do not roll back application writers without also
 restoring the pre-upgrade schema/database backup.
+
+## Hosted OAuth authorization
+
+Use `SmrtOAuthAuthorizationStorage` with the SDK authorization server, and
+`SmrtOAuthAuthorizationService` to bind consent to existing browser sessions:
+
+```typescript
+import { createAuthorizationServer } from '@happyvertical/auth/server';
+import {
+  SmrtOAuthAuthorizationService,
+  SmrtOAuthAuthorizationStorage,
+} from '@happyvertical/smrt-users';
+
+const authorization = await SmrtOAuthAuthorizationService.create({
+  db,
+  scopePermissions: { 'catalog:read': ['catalog.read'] },
+});
+const server = createAuthorizationServer({
+  issuer: 'https://app.example/oauth',
+  signingKey,
+  storage: await SmrtOAuthAuthorizationStorage.create({ db }),
+  identity: authorization.identity,
+  scopes: ['catalog:read'],
+  resources: ['https://app.example/mcp'],
+});
+// After explicit same-origin browser consent:
+const parsed = await server.parseAuthorizationRequest(url.searchParams);
+const redirect = await authorization.approve(server, parsed, sessionId);
+// On every bearer request, verify cryptography AND live authorization:
+const payload = await server.verifyAccessToken(token, 'https://app.example/mcp');
+const context = await authorization.validateAccessTokenClaims(payload);
+if (!context) throw new Error('Authorization is no longer active.');
+```
+
+The SvelteKit export `createOAuthHandlers` supplies optional session-aware
+consent and account-grant routes. `listGrants(sessionId)` and
+`revokeGrant(sessionId, grantId)` confine account management to the signed-in
+subject. Migrate the private `users_oauth_*` tables before enabling the issuer.
+See [OAuth authorization](agents/oauth-authorization.md) for lifecycle,
+revocation, permission ceilings and the database test matrix.
+
+For local SQLite processes sharing a file, configure the storage's optional
+`recoverDatabase` factory to recreate an invalidated connection and reapply its
+settings. Instance-only storage fails closed on an invalidated connection; it
+never silently drops PRAGMAs or temporary state. PostgreSQL does not require
+this option. The [transaction notes](agents/oauth-authorization.md#recoverable-local-sqlite-connections)
+show the factory contract.

package/agents/oauth-authorization.md

@@ -0,0 +1,124 @@
+# Hosted OAuth authorization
+
+`SmrtOAuthAuthorizationStorage` implements the protocol-neutral storage contract
+from `@happyvertical/auth/server`. Apply normal SMRT migrations before starting
+the server. The six `users_oauth_*` models are sensitive and have no generated
+REST, MCP or CLI operations. Keep their tables on the private application
+connection; public catalog roles must not read them.
+
+`SmrtOAuthAuthorizationService.create({ db, scopePermissions })` supplies the
+session boundary. `approve(server, parsedRequest, sessionId)` loads the existing
+session again, checks its active user and tenant membership, verifies every
+scope's configured permissions, and records consent. Existing magic-link,
+password and OIDC sessions work without a separate identity mapping. Parent
+session validity and session permission ceilings are enforced by SessionService.
+Unknown scopes fail closed. An empty permission mapping explicitly permits a
+scope for any valid session. OAuth does not grant super-admin bypass.
+
+Pass `service.identity` to the SDK server. It revalidates the stored consent on
+both code exchange and refresh. A permission loss denies the grant rather than
+silently expanding or partially authorizing it. The consent-time permission
+snapshot is an upper bound even if the host later changes its scope mapping.
+
+After `server.verifyAccessToken(token, resource)`, always call
+`service.validateAccessTokenClaims(payload)`. A non-null result is a server-only
+SessionContext whose permissions and permissionCeiling are limited to the
+verified token's mapped scopes. Do not serialize that context: it contains the
+session credential. The JWT carries only a non-secret `smrt_grant_id`, subject,
+client, tenant and scopes. JWT signature verification alone does not check live
+session, user, tenant or consent revocation.
+
+`listGrants(sessionId)` returns safe account-settings projections.
+`revokeGrant(sessionId, grantId)` checks ownership and atomically revokes the
+consent, outstanding codes, and all refresh descendants. Revoking or replaying a
+managed refresh token also revokes its consent, so existing access tokens fail
+the live grant check. Repeating revocation is safe. A foreign grant returns false.
+
+The `/sveltekit` export `createOAuthHandlers({ server, authorization,
+getSessionId })` provides Fetch-compatible `authorize`, `consent`, `grants` and
+`protocol` handlers. The host renders consent, supplies its existing cookie
+lookup, and preserves a validated local return path through magic-link login.
+Consent POST requires an exact same-origin Origin header and `decision=approve`;
+requested OAuth parameters remain on the authorization URL and are revalidated
+by the SDK. Grant revocation POST has the same origin check and takes `grantId`.
+All account/consent responses use private, no-store. No handler authenticates a
+session from OAuth client identity or accepts a browser-submitted user/tenant.
+
+## Transaction invariants
+
+Code consume uses a conditional write. Refresh rotation and revocation lock a
+stable family row before reading token state; locking the token being replaced
+alone would allow a concurrent revocation to miss an inserted descendant.
+Managed operations lock the consent row first, then the family. Replacement
+insertion, old-token consume and replay revocation share one database executor.
+A failed insert rolls back consume. Revalidated scopes and claims are persisted
+atomically before the SDK exposes the replacement. Undefined claims clear prior
+claims. Narrowing cannot expand scopes, revive or modify a consumed token.
+
+Retry only transaction failures classified as SQLite contention or PostgreSQL
+serialization/deadlock, after adapter rollback, at most six retries. Never retry
+protocol callbacks or other external effects. The database adapter must clean up
+failed statements and support independent connections; a process-local mutex is
+not a replica-safety mechanism.
+
+## Behavior-to-test contract (#3659)
+
+Every row runs in `src/__tests__/oauth-authorization.test.ts` on Node >=26 with
+SQLite and real PostgreSQL. Commands:
+
+```sh
+pnpm --filter @happyvertical/smrt-users exec vitest run src/__tests__/oauth-authorization.test.ts
+DATABASE_URL=postgres://postgres@127.0.0.1:55597/smrt_oauth pnpm --filter @happyvertical/smrt-users exec vitest run src/__tests__/oauth-authorization.test.ts
+pnpm --filter @happyvertical/smrt-users typecheck
+```
+
+| Invariant / trigger | Positive | Negative / failure | Actor / context | Executor / external edge | Level |
+| --- | --- | --- | --- | --- | --- |
+| Register and consume code | Metadata survives new adapter; one concurrent winner | Wrong client, redirect, resource; expiry and replay | Registered client / subject | Independent DB connections; SDK code contract | Integration |
+| Rotate / replay refresh | One replacement | Reuse revokes every descendant | Same family across replicas | Stable family lock, same transaction | Integration |
+| Rotation rollback / revoke race | Retry after insertion failure works | Duplicate replacement aborts consume; revoke cannot miss descendant | Same family, simultaneous operations | Real rollback and independent executors | Integration |
+| Narrow replacement | Subset and replacement claims persist through subsequent rotation; undefined claims clear old claims | Expansion, hash mismatch, consumed/revoked token | Authenticated client / original family | SDK fail-closed narrowing contract, atomic locked update | Integration |
+| Explicit recovery factory | Recreates configured connection after invalidation | Instance-only fails closed; ordinary storage failure propagates | Storage owner / configured database | Injected failure boundary plus real independent-connection races | Unit + integration |
+| Access revocation | Another adapter sees it; repeats safe | Expired revocation no longer effective | Possessor of verified access token | Unique insert with conflict handling | Integration |
+| Consent/grant ownership | Own grant can list/revoke | Other subject, tenant, scope deny; no session bearer in projection | Owner A/B × grant A/B | Live session + consent reads; atomic cascade | Integration |
+| Live identity and ceiling | Current permission allows | Inactive user/membership, changed session ceiling, destroyed session | Active vs revoked context | SessionService and current RBAC | Integration |
+| Code/live revoke cascade | Valid code exchanges | Membership loss before exchange; refresh revoke kills access | Original subject/tenant | SDK revalidateConsent callback | Integration |
+| Consent snapshot / tenant | Original mapped scope | Later permission mapping expansion; inactive tenant | Owner × current tenant | Stored upper bound plus live permission checks | Integration |
+| Layered session / expiry | Parent and child valid | Parent destroyed or child expired | Person session on device parent | Existing session controls | Integration |
+| Consent route | Same-origin explicit approval | Missing/foreign Origin, denial, revoked session | Browser session / untrusted POST | Fetch request and SDK parsing | Route + DB |
+
+This is new functionality, so a base-regression comparison is N/A: base has no
+OAuth authorization storage or session grant API. Positive/negative contract
+cases exercise real persistence rather than mocked SQL. Remote-provider outage
+is N/A: the service has no external identity/provider call. SDK owns malformed
+OAuth protocol, signature, PKCE and redirect parsing tests; hosts own their
+consent UI, login return path and application-specific workspace policy.
+
+### Recoverable local SQLite connections
+
+Local libsql connections may be invalidated by the SQL adapter after a native
+`SQLITE_BUSY` failure. An instance-only storage adapter fails closed in this
+case; it does not silently reconnect and discard connection settings.
+For recoverable local multi-replica operation, supply `recoverDatabase`:
+
+```typescript
+const storage = await SmrtOAuthAuthorizationStorage.create({
+  db,
+  recoverDatabase: async () => {
+    const connection = await getDatabase({
+      type: 'sqlite', url: configuredFileUrl, dbid: randomUUID(),
+    });
+    await connection.query('PRAGMA foreign_keys = ON');
+    // Reapply any other application-required connection settings here.
+    return connection;
+  },
+});
+```
+
+The factory is also used for the initial dedicated storage connection, keeping
+storage recovery independent of a shared application/session connection. It
+must return a migrated connection to the same database and restore every
+required PRAGMA, attachment, temporary table or other per-connection setting.
+It must not create application schema. Known invalidated failures may be retried
+at most six times; ordinary storage failures propagate. PostgreSQL does not
+need this factory. Connection ownership/disposal remains with the host factory.

package/agents/retention.md

@@ -57,3 +57,21 @@ reap them.
   marked `expired` by lazy expiry, and consumed history; it retains approved
   requests until exchange so a near-expiry approval cannot orphan its bearer
   session.
+
+## OAuth credential retention
+
+`users-oauth-credentials` prunes expired authorization codes and access-token
+revocations. Refresh grants (including consumed or revoked hashes) remain until
+30 days after their own expiry, so replay within their validity period and this
+grace period still revokes the family. Later replay fails as an unknown token.
+This bounds retained rotation history even for continuously active families.
+The sweep locks each candidate family using the same row as token rotation,
+rechecks its descendants, and deletes the family only when none remain. Live
+grants and revocations are never swept. Each family is a separate transaction;
+rolled-back contention retries follow the OAuth transaction policy. If the SQL
+adapter invalidates a connection (for example SQLite SQLITE_BUSY), the sweep
+reports failure; the host must acquire a fresh connection before retrying. It
+never continues on an invalidated connection. Dry runs write nothing and
+report approximate counts under concurrent writes. Clients and consent records
+remain for application-managed lifecycle/audit. Opt-out and unregister work as
+for the other retention tasks. No raw bearer or credential hash is logged.