@venturekit/auth 0.0.0-dev.20260701100017 → 0.0.0-dev.20260704225856

package/dist/server/middleware.d.ts

@@ -45,6 +45,16 @@ export interface CookieAuthMiddlewareOptions {
      * tests lets you construct a middleware without touching env.
      */
     config?: AuthServerConfig;
+    /**
+     * Map verified JWT claims to the scope strings the
+     * `handler({ scopes })` gate checks. Defaults to
+     * {@link defaultScopeMapper}, which unions the access-token `scope`
+     * claim with Cognito `cognito:groups` and a `custom:scopes`
+     * attribute — so id-token browser sessions (which carry no `scope`
+     * claim) can still satisfy scoped routes via group / attribute
+     * membership. Provide your own to map app-specific claims.
+     */
+    scopeMapper?: (claims: Record<string, unknown>) => string[];
 }
 /**
  * Build a `@venturekit/runtime` middleware that verifies a session JWT
@@ -73,4 +83,29 @@ export declare function cookieAuthMiddleware(options?: CookieAuthMiddlewareOptio
  * {@link cookieAuthMiddleware} instead.
  */
 export declare function extractToken(event: APIGatewayProxyEventV2, cookieName?: string): string | null;
+/**
+ * Default claims→scopes mapper.
+ *
+ * Unions three sources so BOTH access-token and id-token sessions can
+ * satisfy the `handler({ scopes })` gate:
+ *   - `scope` — space-separated, present on Cognito ACCESS tokens.
+ *   - `cognito:groups` — `string[]` on both id and access tokens; group
+ *     names double as coarse scopes (e.g. a `cms.admin` group satisfies
+ *     `scopes: ['cms.admin']`).
+ *   - `custom:scopes` — a custom user-pool attribute holding a space- or
+ *     comma-separated scope list; the recommended way to attach scopes
+ *     to id-token browser sessions, which otherwise carry no `scope`.
+ *
+ * De-duplicates and drops empties. Override via
+ * {@link CookieAuthMiddlewareOptions.scopeMapper} for app-specific claims.
+ *
+ * # id-token vs access-token (the A2 decision)
+ * The default {@link cookieAuthMiddleware} verifies ID tokens because the
+ * browser session cookie is an id token (it carries `email` + profile).
+ * ID tokens have no OAuth `scope`, so scope gating on id-token sessions
+ * MUST come from Cognito groups or a `custom:scopes` attribute — which
+ * this mapper reads out of the box. For service-to-service callers, use
+ * `cookieAuthMiddleware({ tokenUse: 'access' })` and the `scope` claim.
+ */
+export declare function defaultScopeMapper(claims: Record<string, unknown>): string[];
 //# sourceMappingURL=middleware.d.ts.map

package/dist/server/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKzD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,IAAI,GAAG,QAAQ,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,UAAU,CAAC,cAAc,CAAC,CAiC5B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,UAAU,GAAE,MAAwB,GACnC,MAAM,GAAG,IAAI,CAoBf"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKzD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,IAAI,GAAG,QAAQ,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,UAAU,CAAC,cAAc,CAAC,CAkC5B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,UAAU,GAAE,MAAwB,GACnC,MAAM,GAAG,IAAI,CAoBf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,EAAE,CAiBV"}

package/dist/server/middleware.js

@@ -46,6 +46,7 @@ import { loadAuthServerConfig } from './config.js';
 export function cookieAuthMiddleware(options = {}) {
     const cookieName = options.cookieName ?? ID_TOKEN_COOKIE;
     const tokenUse = options.tokenUse ?? 'id';
+    const scopeMapper = options.scopeMapper ?? defaultScopeMapper;
     // Resolve config lazily so a route module can import the middleware
     // factory at file-load time without the env vars being set (tests,
     // local type-only imports, etc.). The first actual request resolves
@@ -70,7 +71,7 @@ export function cookieAuthMiddleware(options = {}) {
                     ...(cfg.endpoint ? { endpoint: cfg.endpoint } : {}),
                 });
                 if (claims) {
-                    ctx.user = claimsToUserContext(claims);
+                    ctx.user = claimsToUserContext(claims, scopeMapper);
                 }
             }
             return next();
@@ -103,17 +104,56 @@ export function extractToken(event, cookieName = ID_TOKEN_COOKIE) {
         : (headers['cookie'] ?? headers['Cookie']);
     return readCookieFromHeader(cookieHeader, cookieName);
 }
-function claimsToUserContext(claims) {
+/**
+ * Default claims→scopes mapper.
+ *
+ * Unions three sources so BOTH access-token and id-token sessions can
+ * satisfy the `handler({ scopes })` gate:
+ *   - `scope` — space-separated, present on Cognito ACCESS tokens.
+ *   - `cognito:groups` — `string[]` on both id and access tokens; group
+ *     names double as coarse scopes (e.g. a `cms.admin` group satisfies
+ *     `scopes: ['cms.admin']`).
+ *   - `custom:scopes` — a custom user-pool attribute holding a space- or
+ *     comma-separated scope list; the recommended way to attach scopes
+ *     to id-token browser sessions, which otherwise carry no `scope`.
+ *
+ * De-duplicates and drops empties. Override via
+ * {@link CookieAuthMiddlewareOptions.scopeMapper} for app-specific claims.
+ *
+ * # id-token vs access-token (the A2 decision)
+ * The default {@link cookieAuthMiddleware} verifies ID tokens because the
+ * browser session cookie is an id token (it carries `email` + profile).
+ * ID tokens have no OAuth `scope`, so scope gating on id-token sessions
+ * MUST come from Cognito groups or a `custom:scopes` attribute — which
+ * this mapper reads out of the box. For service-to-service callers, use
+ * `cookieAuthMiddleware({ tokenUse: 'access' })` and the `scope` claim.
+ */
+export function defaultScopeMapper(claims) {
+    const out = new Set();
+    const addAll = (raw, splitter) => {
+        if (typeof raw === 'string') {
+            for (const s of raw.split(splitter))
+                if (s)
+                    out.add(s);
+        }
+    };
+    // Access-token scope claim (space-separated).
+    addAll(claims['scope'], / +/);
+    // Cognito groups (array on id + access tokens).
+    const groups = claims['cognito:groups'];
+    if (Array.isArray(groups)) {
+        for (const g of groups)
+            if (typeof g === 'string' && g)
+                out.add(g);
+    }
+    // custom:scopes attribute (space- or comma-separated).
+    addAll(claims['custom:scopes'], /[\s,]+/);
+    return [...out];
+}
+function claimsToUserContext(claims, scopeMapper = defaultScopeMapper) {
     const sub = claims['sub'];
     const email = claims['email'];
-    // `scope` appears on access tokens (space-separated). ID tokens don't
-    // carry scopes; if the app uses ID tokens, scope-based route gating
-    // should be backed by `custom:*` role/scope attributes on the user
-    // pool and mapped in a downstream mapper.
-    const scopeClaim = claims['scope'];
-    const scopes = typeof scopeClaim === 'string'
-        ? scopeClaim.split(' ').filter(Boolean)
-        : [];
+    const scopes = scopeMapper(claims);
     return {
         id: typeof sub === 'string' ? sub : '',
         email: typeof email === 'string' ? email : undefined,

package/dist/server/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"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"}

package/dist/server/passwordless.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Server-verified (passwordless) identity flows.
+ *
+ * For UXes where the APP proves address ownership out-of-band — magic
+ * links, OAuth/OIDC callbacks, emailed one-time codes — and Cognito is
+ * only the identity/token backend, never the credential UI:
+ *
+ *   1. {@link ensureUserForVerifiedEmail} — idempotently create the
+ *      Cognito user (invite email suppressed, `email_verified=true`)
+ *      or fetch the existing one; the returned `sub` doubles as the
+ *      app's `users.id`.
+ *   2. {@link mintSessionForVerifiedEmail} — rotate the user's
+ *      password to a throwaway strong secret (`AdminSetUserPassword`,
+ *      permanent) and immediately sign in via
+ *      `InitiateAuth(USER_PASSWORD_AUTH)`. The password is discarded;
+ *      only the tokens leave the function.
+ *
+ * Requirements:
+ *   - the app client must allow `ALLOW_USER_PASSWORD_AUTH`;
+ *   - the caller's IAM role needs the `cognito-idp:Admin*` actions
+ *     used below (VentureKit's auth intent grants them to the API
+ *     Lambdas).
+ *
+ * Security notes:
+ *   - the rotated password never leaves the server and satisfies the
+ *     default "strong" policy (length + upper/lower/digit/symbol);
+ *   - replays are benign: re-minting just issues another valid token
+ *     set for the same identity — revoke on sign-out;
+ *   - concurrent mints race harmlessly (last rotation wins, every
+ *     token set issued stays valid until expiry/revocation).
+ */
+import type { AuthServerConfig } from './config.js';
+import { type SignInResult } from './tokens.js';
+export interface EnsureUserForVerifiedEmailInput {
+    /** Address the app has already proven ownership of. */
+    email: string;
+    /** Optional standard attributes copied onto the Cognito record. */
+    firstName?: string;
+    lastName?: string;
+    /**
+     * Additional attributes (e.g. `{ 'custom:tenantRoles': '…' }`).
+     * Applied on create AND refreshed on subsequent calls.
+     */
+    attributes?: Record<string, string>;
+}
+export interface EnsureUserForVerifiedEmailResult {
+    /** Cognito `sub` (UUID) — commonly reused as the app's user id. */
+    sub: string;
+    /** True when this call created the Cognito user. */
+    created: boolean;
+}
+/**
+ * Idempotently ensure a Cognito user exists for a server-verified
+ * email. New users are auto-confirmed with `email_verified=true` and
+ * the invite email suppressed — the app owns the UX. On subsequent
+ * calls the profile attributes are refreshed best-effort.
+ */
+export declare function ensureUserForVerifiedEmail(input: EnsureUserForVerifiedEmailInput, config?: AuthServerConfig): Promise<EnsureUserForVerifiedEmailResult>;
+/**
+ * Mint a full token set (id + access + refresh) for a user whose
+ * email the app just verified: rotate the password server-side, sign
+ * in with it, discard it.
+ *
+ * Throws {@link AuthError} when the rotation or sign-in fails (e.g.
+ * `USER_PASSWORD_AUTH` not enabled on the app client).
+ */
+export declare function mintSessionForVerifiedEmail(email: string, config?: AuthServerConfig): Promise<SignInResult>;
+//# sourceMappingURL=passwordless.d.ts.map

package/dist/server/passwordless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwordless.d.ts","sourceRoot":"","sources":["../../src/server/passwordless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAaH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAWrE,MAAM,WAAW,+BAA+B;IAC9C,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,gCAAgC;IAC/C,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,EACtC,MAAM,GAAE,gBAAyC,GAChD,OAAO,CAAC,gCAAgC,CAAC,CAgE3C;AAED;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,gBAAyC,GAChD,OAAO,CAAC,YAAY,CAAC,CAyBvB"}

package/dist/server/passwordless.js

@@ -0,0 +1,136 @@
+/**
+ * Server-verified (passwordless) identity flows.
+ *
+ * For UXes where the APP proves address ownership out-of-band — magic
+ * links, OAuth/OIDC callbacks, emailed one-time codes — and Cognito is
+ * only the identity/token backend, never the credential UI:
+ *
+ *   1. {@link ensureUserForVerifiedEmail} — idempotently create the
+ *      Cognito user (invite email suppressed, `email_verified=true`)
+ *      or fetch the existing one; the returned `sub` doubles as the
+ *      app's `users.id`.
+ *   2. {@link mintSessionForVerifiedEmail} — rotate the user's
+ *      password to a throwaway strong secret (`AdminSetUserPassword`,
+ *      permanent) and immediately sign in via
+ *      `InitiateAuth(USER_PASSWORD_AUTH)`. The password is discarded;
+ *      only the tokens leave the function.
+ *
+ * Requirements:
+ *   - the app client must allow `ALLOW_USER_PASSWORD_AUTH`;
+ *   - the caller's IAM role needs the `cognito-idp:Admin*` actions
+ *     used below (VentureKit's auth intent grants them to the API
+ *     Lambdas).
+ *
+ * Security notes:
+ *   - the rotated password never leaves the server and satisfies the
+ *     default "strong" policy (length + upper/lower/digit/symbol);
+ *   - replays are benign: re-minting just issues another valid token
+ *     set for the same identity — revoke on sign-out;
+ *   - concurrent mints race harmlessly (last rotation wins, every
+ *     token set issued stays valid until expiry/revocation).
+ */
+import { AdminCreateUserCommand, AdminGetUserCommand, AdminSetUserPasswordCommand, AdminUpdateUserAttributesCommand, InitiateAuthCommand, MessageActionType, UsernameExistsException, } from '@aws-sdk/client-cognito-identity-provider';
+import { randomBytes } from 'node:crypto';
+import { loadAuthServerConfig } from './config.js';
+import { getCognitoClient } from './cognito-client.js';
+import { AuthError, mapProviderError } from './errors.js';
+import { extractSignInTokens } from './tokens.js';
+/**
+ * Cryptographically random password satisfying Cognito's default
+ * "strong" policy: 40 base64url chars + `Aa1!` to guarantee the
+ * character-class mix. Internal — the value is never surfaced.
+ */
+function generateRotatingPassword() {
+    return `${randomBytes(30).toString('base64url')}Aa1!`;
+}
+/**
+ * Idempotently ensure a Cognito user exists for a server-verified
+ * email. New users are auto-confirmed with `email_verified=true` and
+ * the invite email suppressed — the app owns the UX. On subsequent
+ * calls the profile attributes are refreshed best-effort.
+ */
+export async function ensureUserForVerifiedEmail(input, config = loadAuthServerConfig()) {
+    const client = getCognitoClient(config.region, config.endpoint);
+    const email = input.email.trim().toLowerCase();
+    const attributes = [
+        { Name: 'email', Value: email },
+        { Name: 'email_verified', Value: 'true' },
+    ];
+    if (input.firstName)
+        attributes.push({ Name: 'given_name', Value: input.firstName });
+    if (input.lastName)
+        attributes.push({ Name: 'family_name', Value: input.lastName });
+    for (const [name, value] of Object.entries(input.attributes ?? {})) {
+        attributes.push({ Name: name, Value: value });
+    }
+    try {
+        const res = await client.send(new AdminCreateUserCommand({
+            UserPoolId: config.userPoolId,
+            Username: email,
+            UserAttributes: attributes,
+            MessageAction: MessageActionType.SUPPRESS,
+        }));
+        const sub = res.User?.Attributes?.find((a) => a.Name === 'sub')?.Value;
+        if (!sub) {
+            throw new AuthError('incomplete_auth_result', 'AdminCreateUser did not return a sub', 500);
+        }
+        return { sub, created: true };
+    }
+    catch (err) {
+        if (!(err instanceof UsernameExistsException)) {
+            throw err instanceof AuthError ? err : mapProviderError(err, 'sign_up_failed');
+        }
+    }
+    // Already present — fetch the sub and refresh mutable attributes.
+    const existing = await client.send(new AdminGetUserCommand({ UserPoolId: config.userPoolId, Username: email }));
+    const sub = existing.UserAttributes?.find((a) => a.Name === 'sub')?.Value;
+    if (!sub) {
+        throw new AuthError('incomplete_auth_result', 'AdminGetUser did not return a sub', 500);
+    }
+    const updates = attributes.filter((a) => a.Name !== 'email' && a.Name !== 'email_verified');
+    if (updates.length) {
+        try {
+            await client.send(new AdminUpdateUserAttributesCommand({
+                UserPoolId: config.userPoolId,
+                Username: email,
+                UserAttributes: updates,
+            }));
+        }
+        catch {
+            // Best-effort — stale profile attributes are not worth failing
+            // an authentication flow over.
+        }
+    }
+    return { sub, created: false };
+}
+/**
+ * Mint a full token set (id + access + refresh) for a user whose
+ * email the app just verified: rotate the password server-side, sign
+ * in with it, discard it.
+ *
+ * Throws {@link AuthError} when the rotation or sign-in fails (e.g.
+ * `USER_PASSWORD_AUTH` not enabled on the app client).
+ */
+export async function mintSessionForVerifiedEmail(email, config = loadAuthServerConfig()) {
+    const client = getCognitoClient(config.region, config.endpoint);
+    const normalized = email.trim().toLowerCase();
+    const password = generateRotatingPassword();
+    try {
+        await client.send(new AdminSetUserPasswordCommand({
+            UserPoolId: config.userPoolId,
+            Username: normalized,
+            Password: password,
+            Permanent: true,
+        }));
+        const res = await client.send(new InitiateAuthCommand({
+            AuthFlow: 'USER_PASSWORD_AUTH',
+            ClientId: config.appClientId,
+            AuthParameters: { USERNAME: normalized, PASSWORD: password },
+        }));
+        return extractSignInTokens(res.AuthenticationResult);
+    }
+    catch (err) {
+        throw err instanceof AuthError ? err : mapProviderError(err, 'sign_in_failed');
+    }
+}
+//# sourceMappingURL=passwordless.js.map

package/dist/server/passwordless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwordless.js","sourceRoot":"","sources":["../../src/server/passwordless.ts"],"names":[],"mappings":"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"}

package/dist/server/revoke.d.ts

@@ -15,4 +15,14 @@ import type { AuthServerConfig } from './config.js';
  * the function never throws.
  */
 export declare function revokeRefreshToken(refreshToken: string, config?: AuthServerConfig): Promise<void>;
+/**
+ * Invalidate EVERY outstanding refresh token for the caller via
+ * Cognito's `GlobalSignOut` (keyed by a valid access token, unlike
+ * {@link revokeRefreshToken} which revokes one refresh token). Already
+ * issued access tokens keep working until natural expiry.
+ *
+ * **Best-effort**, same contract as {@link revokeRefreshToken}: sign-out
+ * must never fail the user, so errors are logged and swallowed.
+ */
+export declare function globalSignOut(accessToken: string, config?: AuthServerConfig): Promise<void>;
 //# sourceMappingURL=revoke.d.ts.map

package/dist/server/revoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"revoke.d.ts","sourceRoot":"","sources":["../../src/server/revoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,gBAAyC,GAChD,OAAO,CAAC,IAAI,CAAC,CAaf"}
+{"version":3,"file":"revoke.d.ts","sourceRoot":"","sources":["../../src/server/revoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,GAAE,gBAAyC,GAChD,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,gBAAyC,GAChD,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/server/revoke.js

@@ -7,7 +7,7 @@
  * because the server-side revoke had a hiccup — the cookies clear
  * regardless.
  */
-import { RevokeTokenCommand } from '@aws-sdk/client-cognito-identity-provider';
+import { GlobalSignOutCommand, RevokeTokenCommand, } from '@aws-sdk/client-cognito-identity-provider';
 import { loadAuthServerConfig } from './config.js';
 import { getCognitoClient } from './cognito-client.js';
 /**
@@ -25,8 +25,25 @@ export async function revokeRefreshToken(refreshToken, config = loadAuthServerCo
         }));
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.warn('[@venturekit/auth/server] refresh-token revoke failed (ignored):', err);
     }
 }
+/**
+ * Invalidate EVERY outstanding refresh token for the caller via
+ * Cognito's `GlobalSignOut` (keyed by a valid access token, unlike
+ * {@link revokeRefreshToken} which revokes one refresh token). Already
+ * issued access tokens keep working until natural expiry.
+ *
+ * **Best-effort**, same contract as {@link revokeRefreshToken}: sign-out
+ * must never fail the user, so errors are logged and swallowed.
+ */
+export async function globalSignOut(accessToken, config = loadAuthServerConfig()) {
+    const client = getCognitoClient(config.region, config.endpoint);
+    try {
+        await client.send(new GlobalSignOutCommand({ AccessToken: accessToken }));
+    }
+    catch (err) {
+        console.warn('[@venturekit/auth/server] global sign-out failed (ignored):', err);
+    }
+}
 //# sourceMappingURL=revoke.js.map

package/dist/server/revoke.js.map

@@ -1 +1 @@
-{"version":3,"file":"revoke.js","sourceRoot":"","sources":["../../src/server/revoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAE/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAAoB,EACpB,SAA2B,oBAAoB,EAAE;IAEjD,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,kBAAkB,CAAC;YACrB,QAAQ,EAAE,MAAM,CAAC,WAAW;YAC5B,KAAK,EAAE,YAAY;SACpB,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,kEAAkE,EAAE,GAAG,CAAC,CAAC;IACxF,CAAC;AACH,CAAC"}
+{"version":3,"file":"revoke.js","sourceRoot":"","sources":["../../src/server/revoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,2CAA2C,CAAC;AAEnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAAoB,EACpB,SAA2B,oBAAoB,EAAE;IAEjD,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,kBAAkB,CAAC;YACrB,QAAQ,EAAE,MAAM,CAAC,WAAW;YAC5B,KAAK,EAAE,YAAY;SACpB,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QAEb,OAAO,CAAC,IAAI,CAAC,kEAAkE,EAAE,GAAG,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,WAAmB,EACnB,SAA2B,oBAAoB,EAAE;IAEjD,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,oBAAoB,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QAEb,OAAO,CAAC,IAAI,CAAC,6DAA6D,EAAE,GAAG,CAAC,CAAC;IACnF,CAAC;AACH,CAAC"}

package/dist/server/store/postgres.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @venturekit/auth — Postgres VerificationCodeStore
+ *
+ * Production {@link VerificationCodeStore} backing the OTP primitives
+ * ({@link requestVerificationCode} / {@link verifyVerificationCode}).
+ * Talks to the project's primary Postgres database via
+ * `@venturekit/data`'s `query()` — or any `Querier`, so the caller can
+ * enlist code writes in an already-open transaction (pass a
+ * `Transaction`'s `query`; the default is the global connection pool).
+ *
+ * The backing table `vk_verification_codes` is shipped by this package's
+ * `migrations/vk_auth_001_verification_codes.sql` and applied by the
+ * in-VPC migration runner `@venturekit/infra` provisions — so consumers
+ * get the table and this store from the same package.
+ *
+ * `@venturekit/data` is an OPTIONAL peer dependency: importing THIS
+ * module is what opts a project into the Postgres store, so apps on a
+ * different backend (DynamoDB, the in-memory dev store) never load it
+ * and `@venturekit/auth/server` stays storage-agnostic.
+ *
+ * `expires_at` crosses the store boundary as ms-epoch to satisfy
+ * {@link VerificationCodeRecord}'s numeric contract: `to_timestamp` on
+ * write, `EXTRACT(EPOCH …) * 1000` on read.
+ */
+import { type Querier } from '@venturekit/data';
+import type { VerificationCodeStore } from '../verification.js';
+/**
+ * Build a Postgres-backed {@link VerificationCodeStore} bound to `q`.
+ *
+ * Pass a transaction's `query` (see `beginTransaction` /
+ * `withTransaction` in `@venturekit/data`) to make code writes
+ * participate in an open transaction; omit it to use the global pool.
+ */
+export declare function createPostgresVerificationCodeStore(q?: Querier): VerificationCodeStore;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/server/store/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../../src/server/store/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAS,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAEV,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAwB5B;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,CAAC,GAAE,OAAe,GACjB,qBAAqB,CAgEvB"}

package/dist/server/store/postgres.js

@@ -0,0 +1,88 @@
+/**
+ * @venturekit/auth — Postgres VerificationCodeStore
+ *
+ * Production {@link VerificationCodeStore} backing the OTP primitives
+ * ({@link requestVerificationCode} / {@link verifyVerificationCode}).
+ * Talks to the project's primary Postgres database via
+ * `@venturekit/data`'s `query()` — or any `Querier`, so the caller can
+ * enlist code writes in an already-open transaction (pass a
+ * `Transaction`'s `query`; the default is the global connection pool).
+ *
+ * The backing table `vk_verification_codes` is shipped by this package's
+ * `migrations/vk_auth_001_verification_codes.sql` and applied by the
+ * in-VPC migration runner `@venturekit/infra` provisions — so consumers
+ * get the table and this store from the same package.
+ *
+ * `@venturekit/data` is an OPTIONAL peer dependency: importing THIS
+ * module is what opts a project into the Postgres store, so apps on a
+ * different backend (DynamoDB, the in-memory dev store) never load it
+ * and `@venturekit/auth/server` stays storage-agnostic.
+ *
+ * `expires_at` crosses the store boundary as ms-epoch to satisfy
+ * {@link VerificationCodeRecord}'s numeric contract: `to_timestamp` on
+ * write, `EXTRACT(EPOCH …) * 1000` on read.
+ */
+import { query } from '@venturekit/data';
+function rowToRecord(r) {
+    return {
+        channel: r.channel,
+        identifier: r.identifier,
+        codeHash: r.code_hash,
+        expiresAt: Number(r.expires_at),
+        attempts: r.attempts,
+        maxAttempts: r.max_attempts,
+    };
+}
+/**
+ * Build a Postgres-backed {@link VerificationCodeStore} bound to `q`.
+ *
+ * Pass a transaction's `query` (see `beginTransaction` /
+ * `withTransaction` in `@venturekit/data`) to make code writes
+ * participate in an open transaction; omit it to use the global pool.
+ */
+export function createPostgresVerificationCodeStore(q = query) {
+    return {
+        async put({ channel, identifier, codeHash, expiresAt, maxAttempts }) {
+            // Opportunistic sweep of already-expired rows on every write —
+            // keeps the table bounded without a dedicated cron (the migration
+            // ships the `expires_at` index that backs this).
+            await q(`DELETE FROM vk_verification_codes WHERE expires_at < CURRENT_TIMESTAMP`);
+            // Idempotent per the store contract: a re-request overwrites the
+            // outstanding code for this (channel, identifier) and resets the
+            // attempt counter — a fresh code means "let me try again", not
+            // "reset the limit on the old one".
+            await q(`INSERT INTO vk_verification_codes
+           (channel, identifier, code_hash, expires_at, attempts, max_attempts)
+         VALUES ($1, $2, $3, to_timestamp($4 / 1000.0), 0, $5)
+         ON CONFLICT (channel, identifier) DO UPDATE
+            SET code_hash    = EXCLUDED.code_hash,
+                expires_at   = EXCLUDED.expires_at,
+                attempts     = 0,
+                max_attempts = EXCLUDED.max_attempts,
+                created_at   = NOW()`, [channel, identifier, codeHash, expiresAt, maxAttempts]);
+        },
+        async get({ channel, identifier }) {
+            // Return the row as-is, INCLUDING when expired — verifyVerificationCode
+            // performs the expiry check and deletes the row itself.
+            return q(`SELECT channel, identifier, code_hash,
+                (EXTRACT(EPOCH FROM expires_at) * 1000)::bigint AS expires_at,
+                attempts, max_attempts
+           FROM vk_verification_codes
+          WHERE channel = $1 AND identifier = $2
+          LIMIT 1`, [channel, identifier], (rows) => {
+                const r = rows[0];
+                return r ? rowToRecord(r) : undefined;
+            });
+        },
+        async incrementAttempts({ channel, identifier }) {
+            return q(`UPDATE vk_verification_codes
+            SET attempts = attempts + 1
+          WHERE channel = $1 AND identifier = $2
+          RETURNING attempts`, [channel, identifier], (rows) => rows[0]?.attempts ?? 0);
+        },
+        async delete({ channel, identifier }) {
+            await q(`DELETE FROM vk_verification_codes WHERE channel = $1 AND identifier = $2`, [channel, identifier]);
+        },
+    };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/server/store/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../../src/server/store/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAgB,MAAM,kBAAkB,CAAC;AAiBvD,SAAS,WAAW,CAAC,CAAsB;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;QAC/B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,WAAW,EAAE,CAAC,CAAC,YAAY;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mCAAmC,CACjD,IAAa,KAAK;IAElB,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE;YACjE,+DAA+D;YAC/D,kEAAkE;YAClE,iDAAiD;YACjD,MAAM,CAAC,CACL,wEAAwE,CACzE,CAAC;YACF,iEAAiE;YACjE,iEAAiE;YACjE,+DAA+D;YAC/D,oCAAoC;YACpC,MAAM,CAAC,CACL;;;;;;;;qCAQ6B,EAC7B,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC,CACxD,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;YAC/B,wEAAwE;YACxE,wDAAwD;YACxD,OAAO,CAAC,CACN;;;;;kBAKU,EACV,CAAC,OAAO,EAAE,UAAU,CAAC,EACrB,CAAC,IAAI,EAAE,EAAE;gBACP,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAA+C,CAAC;gBAChE,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACxC,CAAC,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;YAC7C,OAAO,CAAC,CACN;;;6BAGqB,EACrB,CAAC,OAAO,EAAE,UAAU,CAAC,EACrB,CAAC,IAAI,EAAE,EAAE,CACN,IAAI,CAAC,CAAC,CAAsC,EAAE,QAAQ,IAAI,CAAC,CAC/D,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE;YAClC,MAAM,CAAC,CACL,0EAA0E,EAC1E,CAAC,OAAO,EAAE,UAAU,CAAC,CACtB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/server/token-utils.d.ts

@@ -8,8 +8,9 @@
  * treat those responses as fatal, we derive the remaining lifetime
  * from the access token itself.
  *
- * This file intentionally has no `@venturekit/auth/server` surface
- * exposure — it's consumed by `sign-in.ts` and `refresh.ts` only.
+ * `decodeJwtClaims` IS part of the public surface: consumers that
+ * just minted tokens (sign-in, passwordless flows) read profile
+ * claims from the id token without a redundant verify round-trip.
  */
 /** Cognito's default access-token lifetime (1 hour). */
 export declare const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
@@ -24,4 +25,13 @@ export declare const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
  * `InitiateAuthCommand`). Use `verifyAndDecode` for untrusted input.
  */
 export declare function deriveExpiresInFromJwt(jwt: string, nowSeconds?: number): number;
+/**
+ * Base64url-decode and JSON.parse a JWT payload. Returns `null` on any
+ * failure — callers fall back to a default.
+ *
+ * Does NOT verify the signature — only use on tokens received
+ * directly from the identity provider (e.g. right after sign-in).
+ * Use `verifyAndDecode` for anything that crossed a trust boundary.
+ */
+export declare function decodeJwtClaims<T extends Record<string, unknown> = Record<string, unknown>>(jwt: string): T | null;
 //# sourceMappingURL=token-utils.d.ts.map

package/dist/server/token-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-utils.d.ts","sourceRoot":"","sources":["../../src/server/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wDAAwD;AACxD,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAsC,GACjD,MAAM,CAgBR"}
+{"version":3,"file":"token-utils.d.ts","sourceRoot":"","sources":["../../src/server/token-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wDAAwD;AACxD,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAsC,GACjD,MAAM,CAgBR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzF,GAAG,EAAE,MAAM,GACV,CAAC,GAAG,IAAI,CAYV"}

package/dist/server/token-utils.js

@@ -8,8 +8,9 @@
  * treat those responses as fatal, we derive the remaining lifetime
  * from the access token itself.
  *
- * This file intentionally has no `@venturekit/auth/server` surface
- * exposure — it's consumed by `sign-in.ts` and `refresh.ts` only.
+ * `decodeJwtClaims` IS part of the public surface: consumers that
+ * just minted tokens (sign-in, passwordless flows) read profile
+ * claims from the id token without a redundant verify round-trip.
  */
 /** Cognito's default access-token lifetime (1 hour). */
 export const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
@@ -24,7 +25,7 @@ export const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 3600;
  * `InitiateAuthCommand`). Use `verifyAndDecode` for untrusted input.
  */
 export function deriveExpiresInFromJwt(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
-    const payload = decodeJwtPayload(jwt);
+    const payload = decodeJwtClaims(jwt);
     if (!payload)
         return DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
     const exp = typeof payload.exp === 'number' ? payload.exp : undefined;
@@ -42,8 +43,12 @@ export function deriveExpiresInFromJwt(jwt, nowSeconds = Math.floor(Date.now() /
 /**
  * Base64url-decode and JSON.parse a JWT payload. Returns `null` on any
  * failure — callers fall back to a default.
+ *
+ * Does NOT verify the signature — only use on tokens received
+ * directly from the identity provider (e.g. right after sign-in).
+ * Use `verifyAndDecode` for anything that crossed a trust boundary.
  */
-function decodeJwtPayload(jwt) {
+export function decodeJwtClaims(jwt) {
     if (typeof jwt !== 'string' || jwt.length === 0)
         return null;
     const parts = jwt.split('.');