@venturekit/auth 0.0.0-dev.20260507015944 → 0.0.0-dev.20260511023410

package/dist/server/federated.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Federated sign-in — server-side OAuth Authorization Code flow.
+ *
+ * VentureKit deliberately does NOT enable the Cognito Hosted UI: your
+ * application owns the login screen. The flow is:
+ *
+ *   1. **SPA** — user clicks "Sign in with Google".
+ *   2. **SPA → API** — `POST /auth/federated/google/start { redirectUri }`.
+ *      The `redirectUri` is a page on the SPA itself (e.g.
+ *      `https://app.example.com/auth/google/callback`) and must be
+ *      registered with the IdP as an allowed redirect.
+ *   3. **API → SPA** — `{ authorizeUrl }` plus an HttpOnly cookie
+ *      holding a CSRF `state`. The API computes the URL with
+ *      {@link buildAuthorizeUrl}.
+ *   4. **SPA** navigates to `authorizeUrl`.
+ *   5. **IdP → SPA** — after authentication, the IdP 302s to
+ *      `redirectUri?code=…&state=…`. The SPA reads the query, then
+ *      calls the API again.
+ *   6. **SPA → API** — `POST /auth/federated/google/complete
+ *      { code, state, redirectUri }`. The API:
+ *        - re-checks `state` against the cookie ({@link verifyOAuthState});
+ *        - exchanges the code for tokens at the IdP via
+ *          {@link exchangeAuthorizationCode} (the
+ *          `client_secret` lives in Secrets Manager, never in the SPA);
+ *        - resolves the user's verified profile;
+ *        - calls {@link signInAsFederatedUser} which mints a Cognito
+ *          session for the same email (creating the user on first
+ *          contact).
+ *   7. **API → SPA** — Set-Cookie session + JSON envelope.
+ *
+ * The SPA never sees the `client_secret`, the IdP `access_token`, or
+ * the OAuth `code` after step 6. Cookies stay HttpOnly + SameSite=Lax.
+ *
+ * The OAuth `client_id` / `client_secret` per provider live in the
+ * Secrets Manager placeholder VentureKit provisions when
+ * `AuthIntent.federated` is set; the ARN is exposed as
+ * `COGNITO_FEDERATED_<PROVIDER>_SECRET_ARN` on every Lambda.
+ */
+import type { AuthServerConfig } from './config.js';
+import { type SignInResult } from './tokens.js';
+export type FederatedProvider = 'google' | 'facebook' | 'apple';
+/**
+ * Verified federated profile — the shape every IdP normalizes to
+ * after `exchangeAuthorizationCode` runs.
+ */
+export interface FederatedProfile {
+    /** Stable identifier from the IdP. Google `sub`, Facebook `id`. */
+    externalId: string;
+    /** Verified email. Required — Cognito uses email as the username. */
+    email: string;
+    /** Optional display name, passed through to Cognito's `name` attr. */
+    name?: string;
+}
+export interface FederatedProviderCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Read the OAuth client credentials for `provider` from the Secrets
+ * Manager placeholder VentureKit provisions. The ARN is read from
+ * `COGNITO_FEDERATED_<PROVIDER>_SECRET_ARN` on every Lambda; the
+ * secret value is JSON `{"clientId":"…","clientSecret":"…"}`.
+ *
+ * Cached for the lifetime of the Lambda container — IdP credentials
+ * rotate via Secrets Manager rotation + a redeploy, not per-request.
+ */
+export declare function loadFederatedProviderCredentials(provider: FederatedProvider, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): Promise<FederatedProviderCredentials>;
+/** Test-only — drop the cached credentials between vitest runs. */
+export declare function _resetFederatedCredentialsForTesting(): void;
+/**
+ * Generate a 32-byte URL-safe random string used as the OAuth `state`
+ * parameter. The same value is returned to the SPA (so it can be
+ * appended to `authorizeUrl`) and pinned to the user's browser via an
+ * HttpOnly cookie. {@link verifyOAuthState} performs a constant-time
+ * comparison on the callback.
+ */
+export declare function generateOAuthState(): string;
+/**
+ * Constant-time equality check between the `state` echoed back by the
+ * IdP and the value that was set on the state cookie at `start` time.
+ * Returns `false` for any mismatch including length differences.
+ */
+export declare function verifyOAuthState(fromQuery: string | undefined, fromCookie: string | undefined): boolean;
+export interface BuildAuthorizeUrlInput {
+    provider: FederatedProvider;
+    /**
+     * Where the IdP should redirect after auth. Must be a page on your
+     * SPA and must be registered as an allowed redirect URI in the IdP
+     * console — Google / Facebook reject mismatches.
+     */
+    redirectUri: string;
+    /** Output of {@link generateOAuthState}. */
+    state: string;
+    /** Override default scopes if you need extra IdP permissions. */
+    scopes?: string[];
+    /**
+     * Extra query parameters appended verbatim. Useful for
+     * `prompt=select_account` (Google) or `auth_type=rerequest`
+     * (Facebook re-consent).
+     */
+    extraParams?: Record<string, string>;
+}
+/**
+ * Build the IdP authorize URL the SPA navigates to after `start`.
+ *
+ * Loads the OAuth `client_id` from Secrets Manager (cached). The
+ * `client_secret` is NOT used here — it's only needed at token
+ * exchange.
+ */
+export declare function buildAuthorizeUrl(input: BuildAuthorizeUrlInput, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): Promise<string>;
+export interface ExchangeAuthorizationCodeInput {
+    provider: FederatedProvider;
+    /** The `code` query param the IdP appended to `redirectUri`. */
+    code: string;
+    /**
+     * Must match the `redirectUri` used in `buildAuthorizeUrl`. Both
+     * Google and Facebook compare these byte-for-byte and 400 on a
+     * mismatch.
+     */
+    redirectUri: string;
+}
+/**
+ * Exchange an OAuth `code` for tokens at the IdP, then resolve the
+ * verified `FederatedProfile`. Throws {@link AuthError}
+ * (`federated_token_invalid`, HTTP 401) on any IdP error.
+ */
+export declare function exchangeAuthorizationCode(input: ExchangeAuthorizationCodeInput, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): Promise<FederatedProfile>;
+export interface SignInAsFederatedUserInput {
+    /** Verified profile from {@link exchangeAuthorizationCode}. */
+    profile: FederatedProfile;
+    /** Provider name — recorded as `custom:federated_provider`. */
+    provider: FederatedProvider;
+    /**
+     * Standard Cognito attributes to set on first creation only — e.g.
+     * `{ phone_number: '+212…' }`. Ignored for existing users.
+     */
+    initialAttributes?: Record<string, string>;
+    /**
+     * Custom attributes to set on first creation only — keyed without
+     * the `custom:` prefix (the helper prepends it).
+     */
+    initialCustomAttributes?: Record<string, string>;
+}
+/**
+ * Sign a verified federated user in. Creates the Cognito user on
+ * first contact (idempotent), rotates a server-side password, and
+ * mints session tokens via `ADMIN_USER_PASSWORD_AUTH`.
+ *
+ * Returns the same {@link SignInResult} shape `signInWithPassword`
+ * returns, so cookie / session helpers stay identical.
+ */
+export declare function signInAsFederatedUser(input: SignInAsFederatedUserInput, config?: AuthServerConfig): Promise<SignInResult>;
+//# sourceMappingURL=federated.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"federated.d.ts","sourceRoot":"","sources":["../../src/server/federated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAQD;;;;;;;;GAQG;AACH,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,OAAO,CAAC,4BAA4B,CAAC,CAgEvC;AAED,mEAAmE;AACnE,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAMT;AAyCD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,OAAO,CAAC,MAAM,CAAC,CAejB;AAMD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,EACrC,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,OAAO,CAAC,gBAAgB,CAAC,CA6B3B;AA2JD,MAAM,WAAW,0BAA0B;IACzC,+DAA+D;IAC/D,OAAO,EAAE,gBAAgB,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,0BAA0B,EACjC,MAAM,GAAE,gBAAyC,GAChD,OAAO,CAAC,YAAY,CAAC,CA6HvB"}

package/dist/server/federated.js

@@ -0,0 +1,436 @@
+/**
+ * Federated sign-in — server-side OAuth Authorization Code flow.
+ *
+ * VentureKit deliberately does NOT enable the Cognito Hosted UI: your
+ * application owns the login screen. The flow is:
+ *
+ *   1. **SPA** — user clicks "Sign in with Google".
+ *   2. **SPA → API** — `POST /auth/federated/google/start { redirectUri }`.
+ *      The `redirectUri` is a page on the SPA itself (e.g.
+ *      `https://app.example.com/auth/google/callback`) and must be
+ *      registered with the IdP as an allowed redirect.
+ *   3. **API → SPA** — `{ authorizeUrl }` plus an HttpOnly cookie
+ *      holding a CSRF `state`. The API computes the URL with
+ *      {@link buildAuthorizeUrl}.
+ *   4. **SPA** navigates to `authorizeUrl`.
+ *   5. **IdP → SPA** — after authentication, the IdP 302s to
+ *      `redirectUri?code=…&state=…`. The SPA reads the query, then
+ *      calls the API again.
+ *   6. **SPA → API** — `POST /auth/federated/google/complete
+ *      { code, state, redirectUri }`. The API:
+ *        - re-checks `state` against the cookie ({@link verifyOAuthState});
+ *        - exchanges the code for tokens at the IdP via
+ *          {@link exchangeAuthorizationCode} (the
+ *          `client_secret` lives in Secrets Manager, never in the SPA);
+ *        - resolves the user's verified profile;
+ *        - calls {@link signInAsFederatedUser} which mints a Cognito
+ *          session for the same email (creating the user on first
+ *          contact).
+ *   7. **API → SPA** — Set-Cookie session + JSON envelope.
+ *
+ * The SPA never sees the `client_secret`, the IdP `access_token`, or
+ * the OAuth `code` after step 6. Cookies stay HttpOnly + SameSite=Lax.
+ *
+ * The OAuth `client_id` / `client_secret` per provider live in the
+ * Secrets Manager placeholder VentureKit provisions when
+ * `AuthIntent.federated` is set; the ARN is exposed as
+ * `COGNITO_FEDERATED_<PROVIDER>_SECRET_ARN` on every Lambda.
+ */
+import { AdminCreateUserCommand, AdminGetUserCommand, AdminInitiateAuthCommand, AdminSetUserPasswordCommand, AdminUpdateUserAttributesCommand, } from '@aws-sdk/client-cognito-identity-provider';
+import { createHmac, randomBytes, timingSafeEqual } 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';
+// ────────────────────────────────────────────────────────────────────
+// Provider-credential resolution (Secrets Manager → cached)
+// ────────────────────────────────────────────────────────────────────
+const credentialsCache = new Map();
+/**
+ * Read the OAuth client credentials for `provider` from the Secrets
+ * Manager placeholder VentureKit provisions. The ARN is read from
+ * `COGNITO_FEDERATED_<PROVIDER>_SECRET_ARN` on every Lambda; the
+ * secret value is JSON `{"clientId":"…","clientSecret":"…"}`.
+ *
+ * Cached for the lifetime of the Lambda container — IdP credentials
+ * rotate via Secrets Manager rotation + a redeploy, not per-request.
+ */
+export async function loadFederatedProviderCredentials(provider, env = process.env) {
+    const cached = credentialsCache.get(provider);
+    if (cached)
+        return cached;
+    const envVar = `COGNITO_FEDERATED_${provider.toUpperCase()}_SECRET_ARN`;
+    const arn = env[envVar];
+    if (!arn) {
+        throw new AuthError('federated_provider_not_configured', `[${provider}] missing env var ${envVar} — declare ` +
+            `\`federated: ['${provider}']\` on the auth intent in vk.config.ts ` +
+            `so VentureKit provisions the Secrets Manager placeholder, then ` +
+            `populate it with the OAuth client credentials from the IdP console.`, 500);
+    }
+    const { SecretsManagerClient, GetSecretValueCommand } = await import('@aws-sdk/client-secrets-manager');
+    const client = new SecretsManagerClient({
+        region: env['AWS_REGION'] ?? env['COGNITO_REGION'],
+    });
+    const res = await client.send(new GetSecretValueCommand({ SecretId: arn }));
+    if (!res.SecretString) {
+        throw new AuthError('federated_provider_not_configured', `[${provider}] Secrets Manager entry ${arn} is empty`, 500);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(res.SecretString);
+    }
+    catch {
+        throw new AuthError('federated_provider_not_configured', `[${provider}] Secrets Manager entry ${arn} is not valid JSON`, 500);
+    }
+    if (!parsed.clientId ||
+        !parsed.clientSecret ||
+        parsed.clientId === 'PLACEHOLDER' ||
+        parsed.clientSecret === 'PLACEHOLDER') {
+        throw new AuthError('federated_provider_not_configured', `[${provider}] Secrets Manager entry ${arn} still holds the ` +
+            `placeholder. Populate it with the OAuth client id + secret ` +
+            `from the IdP console: aws secretsmanager put-secret-value ` +
+            `--secret-id ${arn} --secret-string '{"clientId":"…","clientSecret":"…"}'`, 500);
+    }
+    const creds = {
+        clientId: parsed.clientId,
+        clientSecret: parsed.clientSecret,
+    };
+    credentialsCache.set(provider, creds);
+    return creds;
+}
+/** Test-only — drop the cached credentials between vitest runs. */
+export function _resetFederatedCredentialsForTesting() {
+    credentialsCache.clear();
+}
+// ────────────────────────────────────────────────────────────────────
+// CSRF state — random token, signed cookie
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Generate a 32-byte URL-safe random string used as the OAuth `state`
+ * parameter. The same value is returned to the SPA (so it can be
+ * appended to `authorizeUrl`) and pinned to the user's browser via an
+ * HttpOnly cookie. {@link verifyOAuthState} performs a constant-time
+ * comparison on the callback.
+ */
+export function generateOAuthState() {
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Constant-time equality check between the `state` echoed back by the
+ * IdP and the value that was set on the state cookie at `start` time.
+ * Returns `false` for any mismatch including length differences.
+ */
+export function verifyOAuthState(fromQuery, fromCookie) {
+    if (!fromQuery || !fromCookie)
+        return false;
+    const a = Buffer.from(fromQuery);
+    const b = Buffer.from(fromCookie);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+const PROVIDER_ENDPOINTS = {
+    google: {
+        authorize: 'https://accounts.google.com/o/oauth2/v2/auth',
+        token: 'https://oauth2.googleapis.com/token',
+        // `openid email profile` returns an `id_token` (JWT) we can decode
+        // for the verified profile without a second `/userinfo` call.
+        defaultScopes: ['openid', 'email', 'profile'],
+    },
+    facebook: {
+        authorize: 'https://www.facebook.com/v18.0/dialog/oauth',
+        token: 'https://graph.facebook.com/v18.0/oauth/access_token',
+        // `email` is required to read the address; `public_profile` is
+        // implicit but listing it makes the consent screen explicit.
+        defaultScopes: ['email', 'public_profile'],
+    },
+    apple: {
+        authorize: 'https://appleid.apple.com/auth/authorize',
+        token: 'https://appleid.apple.com/auth/token',
+        // Apple wants `name email`; `response_mode=form_post` is required
+        // when scopes include `name`/`email` — callers should set it.
+        defaultScopes: ['name', 'email'],
+    },
+};
+/**
+ * Build the IdP authorize URL the SPA navigates to after `start`.
+ *
+ * Loads the OAuth `client_id` from Secrets Manager (cached). The
+ * `client_secret` is NOT used here — it's only needed at token
+ * exchange.
+ */
+export async function buildAuthorizeUrl(input, env = process.env) {
+    const { provider, redirectUri, state, scopes, extraParams } = input;
+    const { clientId } = await loadFederatedProviderCredentials(provider, env);
+    const endpoints = PROVIDER_ENDPOINTS[provider];
+    const url = new URL(endpoints.authorize);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', clientId);
+    url.searchParams.set('redirect_uri', redirectUri);
+    url.searchParams.set('scope', (scopes ?? endpoints.defaultScopes).join(' '));
+    url.searchParams.set('state', state);
+    for (const [k, v] of Object.entries(extraParams ?? {})) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+/**
+ * Exchange an OAuth `code` for tokens at the IdP, then resolve the
+ * verified `FederatedProfile`. Throws {@link AuthError}
+ * (`federated_token_invalid`, HTTP 401) on any IdP error.
+ */
+export async function exchangeAuthorizationCode(input, env = process.env) {
+    const { provider, code, redirectUri } = input;
+    const { clientId, clientSecret } = await loadFederatedProviderCredentials(provider, env);
+    switch (provider) {
+        case 'google':
+            return exchangeGoogle(code, redirectUri, clientId, clientSecret);
+        case 'facebook':
+            return exchangeFacebook(code, redirectUri, clientId, clientSecret);
+        case 'apple':
+            throw new AuthError('federated_provider_not_configured', 'Sign in with Apple requires a JWT-signed client_secret rotated ' +
+                'every 6 months — implement the Apple-specific exchange in your ' +
+                'application until VentureKit ships a built-in helper.', 500);
+        default: {
+            const _exhaustive = provider;
+            void _exhaustive;
+            throw new AuthError('federated_provider_not_configured', `Unknown federated provider: ${String(provider)}`, 500);
+        }
+    }
+}
+async function exchangeGoogle(code, redirectUri, clientId, clientSecret) {
+    // Google's token endpoint accepts application/x-www-form-urlencoded
+    // and returns `{ access_token, id_token, expires_in, ... }`. We only
+    // need the id_token: it's a signed JWT carrying `sub`, `email`,
+    // `email_verified`, `name`. Signature verification is unnecessary
+    // because we just received it from Google's TLS endpoint over a
+    // back-channel call we initiated — there's no way for an attacker
+    // to substitute it. (Per Google's docs:
+    // https://developers.google.com/identity/openid-connect/openid-connect#validatinganidtoken)
+    const body = new URLSearchParams({
+        code,
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uri: redirectUri,
+        grant_type: 'authorization_code',
+    });
+    const tokenRes = await fetch(PROVIDER_ENDPOINTS.google.token, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body,
+    });
+    if (!tokenRes.ok) {
+        throw new AuthError('federated_token_invalid', `Google token exchange failed (HTTP ${tokenRes.status}): ` +
+            (await tokenRes.text().catch(() => '')), 401);
+    }
+    const tokenJson = (await tokenRes.json());
+    if (!tokenJson.id_token) {
+        throw new AuthError('federated_token_invalid', 'Google token exchange returned no id_token', 401);
+    }
+    const claims = decodeJwtPayload(tokenJson.id_token);
+    const sub = typeof claims['sub'] === 'string' ? claims['sub'] : null;
+    const email = typeof claims['email'] === 'string'
+        ? claims['email'].toLowerCase()
+        : null;
+    const emailVerified = claims['email_verified'] === true;
+    if (!sub || !email || !emailVerified) {
+        throw new AuthError('federated_token_invalid', 'Google id_token missing required verified email claim', 401);
+    }
+    const name = typeof claims['name'] === 'string' ? claims['name'] : undefined;
+    return { externalId: sub, email, name };
+}
+async function exchangeFacebook(code, redirectUri, clientId, clientSecret) {
+    // Facebook's token endpoint accepts the same params as a GET. The
+    // response is `{ access_token, token_type, expires_in }`. There's
+    // no id_token, so we follow up with a Graph `/me` call.
+    const tokenUrl = new URL(PROVIDER_ENDPOINTS.facebook.token);
+    tokenUrl.searchParams.set('code', code);
+    tokenUrl.searchParams.set('client_id', clientId);
+    tokenUrl.searchParams.set('client_secret', clientSecret);
+    tokenUrl.searchParams.set('redirect_uri', redirectUri);
+    const tokenRes = await fetch(tokenUrl);
+    if (!tokenRes.ok) {
+        throw new AuthError('federated_token_invalid', `Facebook token exchange failed (HTTP ${tokenRes.status}): ` +
+            (await tokenRes.text().catch(() => '')), 401);
+    }
+    const tokenJson = (await tokenRes.json());
+    if (!tokenJson.access_token) {
+        throw new AuthError('federated_token_invalid', 'Facebook token exchange returned no access_token', 401);
+    }
+    // appsecret_proof = HMAC_SHA256(access_token, app_secret) — Meta
+    // requires it for sensitive scopes and recommends it for everything.
+    const proof = createHmac('sha256', clientSecret)
+        .update(tokenJson.access_token)
+        .digest('hex');
+    const meUrl = new URL('https://graph.facebook.com/v18.0/me');
+    meUrl.searchParams.set('fields', 'id,email,name');
+    meUrl.searchParams.set('access_token', tokenJson.access_token);
+    meUrl.searchParams.set('appsecret_proof', proof);
+    const meRes = await fetch(meUrl);
+    if (!meRes.ok) {
+        throw new AuthError('federated_token_invalid', `Facebook /me failed (HTTP ${meRes.status})`, 401);
+    }
+    const me = (await meRes.json());
+    if (!me.id || !me.email) {
+        throw new AuthError('federated_token_invalid', 'Facebook profile missing id or email — request the `email` scope.', 401);
+    }
+    return {
+        externalId: me.id,
+        email: me.email.toLowerCase(),
+        name: me.name,
+    };
+}
+/**
+ * Decode a JWT payload **without** verifying the signature. Safe here
+ * because the caller just fetched the token over TLS from the IdP's
+ * own token endpoint; the decoder is internal-only.
+ */
+function decodeJwtPayload(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length < 2) {
+        throw new AuthError('federated_token_invalid', 'Malformed JWT', 401);
+    }
+    try {
+        const payload = Buffer.from(parts[1], 'base64url').toString('utf-8');
+        return JSON.parse(payload);
+    }
+    catch {
+        throw new AuthError('federated_token_invalid', 'Malformed JWT', 401);
+    }
+}
+/**
+ * Sign a verified federated user in. Creates the Cognito user on
+ * first contact (idempotent), rotates a server-side password, and
+ * mints session tokens via `ADMIN_USER_PASSWORD_AUTH`.
+ *
+ * Returns the same {@link SignInResult} shape `signInWithPassword`
+ * returns, so cookie / session helpers stay identical.
+ */
+export async function signInAsFederatedUser(input, config = loadAuthServerConfig()) {
+    const client = getCognitoClient(config.region, config.endpoint);
+    const email = input.profile.email.toLowerCase();
+    // Generate a strong server-side password every sign-in so even if
+    // the value were ever exfiltrated it'd already be replaced. The
+    // user never sees this password — federated sign-in never exposes
+    // it; password sign-in for the same account is still possible
+    // after a `forgot-password` flow.
+    const password = generateStrongPassword();
+    let userExists;
+    try {
+        await client.send(new AdminGetUserCommand({
+            UserPoolId: config.userPoolId,
+            Username: email,
+        }));
+        userExists = true;
+    }
+    catch (err) {
+        if (err.name === 'UserNotFoundException') {
+            userExists = false;
+        }
+        else {
+            throw mapProviderError(err, 'federated_signin_failed');
+        }
+    }
+    if (!userExists) {
+        const attrs = [
+            { Name: 'email', Value: email },
+            { Name: 'email_verified', Value: 'true' },
+        ];
+        if (input.profile.name) {
+            attrs.push({ Name: 'name', Value: input.profile.name });
+        }
+        for (const [k, v] of Object.entries(input.initialAttributes ?? {})) {
+            if (k === 'email' || k === 'email_verified' || k === 'name')
+                continue;
+            attrs.push({ Name: k, Value: v });
+        }
+        attrs.push({
+            Name: 'custom:federated_provider',
+            Value: input.provider,
+        });
+        for (const [k, v] of Object.entries(input.initialCustomAttributes ?? {})) {
+            attrs.push({ Name: `custom:${k}`, Value: v });
+        }
+        try {
+            await client.send(new AdminCreateUserCommand({
+                UserPoolId: config.userPoolId,
+                Username: email,
+                UserAttributes: attrs,
+                // Suppress the welcome email — the user just authenticated
+                // through the IdP, they don't need a Cognito-generated one.
+                MessageAction: 'SUPPRESS',
+                TemporaryPassword: password,
+            }));
+        }
+        catch (err) {
+            // `UsernameExistsException` here is a race between two parallel
+            // federated sign-ins for the same email — fall through to the
+            // password reset + auth path; both will succeed.
+            if (err.name !== 'UsernameExistsException') {
+                throw mapProviderError(err, 'federated_signin_failed');
+            }
+        }
+    }
+    else {
+        // Existing user — make sure email is marked verified (older
+        // password-only signups may have `email_verified=false` if the
+        // confirmation email was never clicked) so `AdminInitiateAuth`
+        // doesn't raise a verification challenge.
+        try {
+            await client.send(new AdminUpdateUserAttributesCommand({
+                UserPoolId: config.userPoolId,
+                Username: email,
+                UserAttributes: [
+                    { Name: 'email', Value: email },
+                    { Name: 'email_verified', Value: 'true' },
+                ],
+            }));
+        }
+        catch (err) {
+            throw mapProviderError(err, 'federated_signin_failed');
+        }
+    }
+    // Set a fresh permanent password whether the user is new (the
+    // temporary one above lands them in `FORCE_CHANGE_PASSWORD`) or
+    // returning. `Permanent: true` skips the new-password challenge.
+    try {
+        await client.send(new AdminSetUserPasswordCommand({
+            UserPoolId: config.userPoolId,
+            Username: email,
+            Password: password,
+            Permanent: true,
+        }));
+    }
+    catch (err) {
+        throw mapProviderError(err, 'federated_signin_failed');
+    }
+    let res;
+    try {
+        res = await client.send(new AdminInitiateAuthCommand({
+            UserPoolId: config.userPoolId,
+            ClientId: config.appClientId,
+            AuthFlow: 'ADMIN_USER_PASSWORD_AUTH',
+            AuthParameters: { USERNAME: email, PASSWORD: password },
+        }));
+    }
+    catch (err) {
+        throw mapProviderError(err, 'federated_signin_failed');
+    }
+    if (res.ChallengeName) {
+        throw new AuthError('federated_signin_failed', `Cognito returned an unexpected challenge after federated sign-in: ${res.ChallengeName}`, 500);
+    }
+    return extractSignInTokens(res.AuthenticationResult);
+}
+/**
+ * Generate a 32-char password that satisfies the strongest password
+ * policy VentureKit ships (`passwordStrength: 'strong'` — 12+ chars,
+ * upper, lower, digit, symbol).
+ */
+function generateStrongPassword() {
+    const base = randomBytes(24)
+        .toString('base64')
+        .replace(/[^A-Za-z0-9]/g, '')
+        .slice(0, 28);
+    return `Aa1!${base}`;
+}
+//# sourceMappingURL=federated.js.map

package/dist/server/federated.js.map

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

package/dist/server/index.d.ts

@@ -43,4 +43,8 @@ export type { SessionTokens, CookieOptions } from './cookies.js';
 export { ID_TOKEN_COOKIE, ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, buildSessionCookies, buildClearSessionCookies, readCookieFromHeader, } from './cookies.js';
 export type { CookieAuthMiddlewareOptions } from './middleware.js';
 export { cookieAuthMiddleware, extractToken } from './middleware.js';
+export type { FederatedProvider, FederatedProfile, FederatedProviderCredentials, SignInAsFederatedUserInput, BuildAuthorizeUrlInput, ExchangeAuthorizationCodeInput, } from './federated.js';
+export { loadFederatedProviderCredentials, generateOAuthState, verifyOAuthState, buildAuthorizeUrl, exchangeAuthorizationCode, signInAsFederatedUser, } from './federated.js';
+export type { VerificationChannel, VerificationCodeStore, VerificationCodeRecord, RequestVerificationCodeInput, RequestVerificationCodeResult, VerifyVerificationCodeInput, } from './verification.js';
+export { generateVerificationCode, hashVerificationCode, requestVerificationCode, verifyVerificationCode, createInMemoryVerificationCodeStore, } from './verification.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,YAAY,EACV,eAAe,EACf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,YAAY,EACV,eAAe,EACf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAErE,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,4BAA4B,EAC5B,0BAA0B,EAC1B,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,mBAAmB,CAAC"}

package/dist/server/index.js

@@ -33,4 +33,6 @@ export { changePassword } from './change-password.js';
 export { verifyAndDecode } from './verify.js';
 export { ID_TOKEN_COOKIE, ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, buildSessionCookies, buildClearSessionCookies, readCookieFromHeader, } from './cookies.js';
 export { cookieAuthMiddleware, extractToken } from './middleware.js';
+export { loadFederatedProviderCredentials, generateOAuthState, verifyOAuthState, buildAuthorizeUrl, exchangeAuthorizationCode, signInAsFederatedUser, } from './federated.js';
+export { generateVerificationCode, hashVerificationCode, requestVerificationCode, verifyVerificationCode, createInMemoryVerificationCodeStore, } from './verification.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOlD,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOlD,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAUrE,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAUxB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,mBAAmB,CAAC"}

package/dist/server/verification.d.ts

@@ -0,0 +1,148 @@
+/**
+ * One-time verification codes (OTP) for sign-up and sign-in.
+ *
+ * Generic primitives for the "we'll text/email you a 6-digit code"
+ * pattern that gates registration when an app wants to confirm an
+ * email or phone number before it ever lives in Cognito. The code
+ * channel is opaque to this module — the caller plugs in `email` /
+ * `whatsapp` / `sms` and decides how to deliver the code (typically
+ * via `@venturekit/notify`).
+ *
+ * Storage is also pluggable via {@link VerificationCodeStore} so
+ * applications can pick Postgres, DynamoDB, or in-memory (tests). The
+ * stored value is a SHA-256 hash of the code, never the code itself —
+ * if the table leaks the codes are still useless.
+ *
+ * Usage sketch (route handler):
+ *
+ * ```ts
+ * // Step 1 — user submits email, we send a code
+ * const { code } = await requestVerificationCode({
+ *   channel: 'email',
+ *   identifier: email,
+ *   store,
+ * });
+ * await notify.sendEmail({ to: email, subject: 'Code', text: code });
+ *
+ * // Step 2 — user submits the code; we verify it
+ * await verifyVerificationCode({
+ *   channel: 'email', identifier: email, code: req.body.code, store,
+ * });
+ * await signUpUser({ email, password });
+ * ```
+ */
+/** A delivery channel — `email`, `sms`, `whatsapp`, or anything else. */
+export type VerificationChannel = string;
+/**
+ * Pluggable storage for outstanding codes. Implementations must be
+ * idempotent on `put` (overwrite previous code for the same key) and
+ * return `undefined` for unknown / expired keys on `get`.
+ *
+ * Keys are tuples of `(channel, identifier)`; e.g.
+ * `('email', 'foo@example.com')` and `('whatsapp', '+212600000000')`
+ * occupy distinct slots so a user with both can verify each one.
+ */
+export interface VerificationCodeStore {
+    put(input: {
+        channel: VerificationChannel;
+        identifier: string;
+        /** SHA-256 hex digest of the plaintext code. */
+        codeHash: string;
+        /** Wall-clock expiry, ms epoch. */
+        expiresAt: number;
+        /** Number of failed `verify` attempts allowed before rotation. */
+        maxAttempts: number;
+    }): Promise<void>;
+    get(input: {
+        channel: VerificationChannel;
+        identifier: string;
+    }): Promise<VerificationCodeRecord | undefined>;
+    /**
+     * Increment the attempt counter for an outstanding code (after a
+     * mismatch). Returning the new counter lets the helper decide
+     * whether to delete the record on the spot once the limit is hit.
+     */
+    incrementAttempts(input: {
+        channel: VerificationChannel;
+        identifier: string;
+    }): Promise<number>;
+    delete(input: {
+        channel: VerificationChannel;
+        identifier: string;
+    }): Promise<void>;
+}
+export interface VerificationCodeRecord {
+    channel: VerificationChannel;
+    identifier: string;
+    codeHash: string;
+    expiresAt: number;
+    attempts: number;
+    maxAttempts: number;
+}
+/**
+ * Generate a random numeric code of `length` digits (default 6).
+ * Uses `crypto.randomInt` so each digit is uniformly distributed —
+ * `Math.random()` would NOT meet the bar for an authentication code.
+ */
+export declare function generateVerificationCode(length?: number): string;
+/**
+ * Hash a code with SHA-256. Stored hashes use this exact function so
+ * `verifyVerificationCode` can recompute the digest and
+ * constant-time-compare. We don't bother with bcrypt/scrypt: codes
+ * live for minutes, not years, and brute-forcing 6 digits in <5
+ * minutes is what `maxAttempts` is for.
+ */
+export declare function hashVerificationCode(code: string): string;
+export interface RequestVerificationCodeInput {
+    channel: VerificationChannel;
+    /** Email, phone number, etc. — opaque to the helper. */
+    identifier: string;
+    store: VerificationCodeStore;
+    /** Code length in digits. Default 6. */
+    length?: number;
+    /** TTL in seconds. Default 600 (10 minutes). */
+    ttlSeconds?: number;
+    /** Max wrong-attempts before the code self-destructs. Default 5. */
+    maxAttempts?: number;
+}
+export interface RequestVerificationCodeResult {
+    /** The plaintext code — caller is responsible for delivery. */
+    code: string;
+    /** Wall-clock expiry, ms epoch. */
+    expiresAt: number;
+}
+/**
+ * Mint a fresh code and store its hash. Overwrites any previous code
+ * for the same `(channel, identifier)` so a user who didn't receive
+ * the first email can hit "resend" without touching state manually.
+ *
+ * Returns the plaintext code so the caller can deliver it via
+ * email / WhatsApp / SMS. The plaintext never re-enters this module.
+ */
+export declare function requestVerificationCode(input: RequestVerificationCodeInput): Promise<RequestVerificationCodeResult>;
+export interface VerifyVerificationCodeInput {
+    channel: VerificationChannel;
+    identifier: string;
+    /** Plaintext code submitted by the user. */
+    code: string;
+    store: VerificationCodeStore;
+}
+/**
+ * Verify a submitted code. On success the record is deleted (codes
+ * are single-use). On mismatch the attempt counter is bumped; once
+ * `maxAttempts` is reached the record is wiped and the next call
+ * looks like "no code requested" — the user has to start over.
+ *
+ * Throws {@link AuthError} (`verification_failed`, HTTP 401) on any
+ * failure path so route handlers can surface a single error to the
+ * SPA without leaking which path was taken.
+ */
+export declare function verifyVerificationCode(input: VerifyVerificationCodeInput): Promise<void>;
+/**
+ * Process-local store. Useful in unit tests and local `vk dev` runs
+ * (single Lambda warm container); never use in production — codes
+ * vanish on cold start, and parallel containers don't see each
+ * other's records.
+ */
+export declare function createInMemoryVerificationCodeStore(): VerificationCodeStore;
+//# sourceMappingURL=verification.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../../src/server/verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,KAAK,EAAE;QACT,OAAO,EAAE,mBAAmB,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,gDAAgD;QAChD,QAAQ,EAAE,MAAM,CAAC;QACjB,mCAAmC;QACnC,SAAS,EAAE,MAAM,CAAC;QAClB,kEAAkE;QAClE,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,GAAG,CAAC,KAAK,EAAE;QACT,OAAO,EAAE,mBAAmB,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAChD;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,EAAE;QACvB,OAAO,EAAE,mBAAmB,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpB,MAAM,CAAC,KAAK,EAAE;QACZ,OAAO,EAAE,mBAAmB,CAAC;QAC7B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAI,GAAG,MAAM,CAW3D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAMD,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,6BAA6B,CAAC,CAexC;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,qBAAqB,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,IAAI,CAAC,CAsDf;AAMD;;;;;GAKG;AACH,wBAAgB,mCAAmC,IAAI,qBAAqB,CA2B3E"}

package/dist/server/verification.js

@@ -0,0 +1,177 @@
+/**
+ * One-time verification codes (OTP) for sign-up and sign-in.
+ *
+ * Generic primitives for the "we'll text/email you a 6-digit code"
+ * pattern that gates registration when an app wants to confirm an
+ * email or phone number before it ever lives in Cognito. The code
+ * channel is opaque to this module — the caller plugs in `email` /
+ * `whatsapp` / `sms` and decides how to deliver the code (typically
+ * via `@venturekit/notify`).
+ *
+ * Storage is also pluggable via {@link VerificationCodeStore} so
+ * applications can pick Postgres, DynamoDB, or in-memory (tests). The
+ * stored value is a SHA-256 hash of the code, never the code itself —
+ * if the table leaks the codes are still useless.
+ *
+ * Usage sketch (route handler):
+ *
+ * ```ts
+ * // Step 1 — user submits email, we send a code
+ * const { code } = await requestVerificationCode({
+ *   channel: 'email',
+ *   identifier: email,
+ *   store,
+ * });
+ * await notify.sendEmail({ to: email, subject: 'Code', text: code });
+ *
+ * // Step 2 — user submits the code; we verify it
+ * await verifyVerificationCode({
+ *   channel: 'email', identifier: email, code: req.body.code, store,
+ * });
+ * await signUpUser({ email, password });
+ * ```
+ */
+import { createHash, randomInt, timingSafeEqual } from 'node:crypto';
+import { AuthError } from './errors.js';
+// ────────────────────────────────────────────────────────────────────
+// Primitives
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Generate a random numeric code of `length` digits (default 6).
+ * Uses `crypto.randomInt` so each digit is uniformly distributed —
+ * `Math.random()` would NOT meet the bar for an authentication code.
+ */
+export function generateVerificationCode(length = 6) {
+    if (length < 4 || length > 10) {
+        throw new Error(`[verification] code length ${length} outside the supported 4–10 range`);
+    }
+    let out = '';
+    for (let i = 0; i < length; i++) {
+        out += String(randomInt(0, 10));
+    }
+    return out;
+}
+/**
+ * Hash a code with SHA-256. Stored hashes use this exact function so
+ * `verifyVerificationCode` can recompute the digest and
+ * constant-time-compare. We don't bother with bcrypt/scrypt: codes
+ * live for minutes, not years, and brute-forcing 6 digits in <5
+ * minutes is what `maxAttempts` is for.
+ */
+export function hashVerificationCode(code) {
+    return createHash('sha256').update(code).digest('hex');
+}
+/**
+ * Mint a fresh code and store its hash. Overwrites any previous code
+ * for the same `(channel, identifier)` so a user who didn't receive
+ * the first email can hit "resend" without touching state manually.
+ *
+ * Returns the plaintext code so the caller can deliver it via
+ * email / WhatsApp / SMS. The plaintext never re-enters this module.
+ */
+export async function requestVerificationCode(input) {
+    const length = input.length ?? 6;
+    const ttlSeconds = input.ttlSeconds ?? 600;
+    const maxAttempts = input.maxAttempts ?? 5;
+    const code = generateVerificationCode(length);
+    const codeHash = hashVerificationCode(code);
+    const expiresAt = Date.now() + ttlSeconds * 1000;
+    await input.store.put({
+        channel: input.channel,
+        identifier: input.identifier,
+        codeHash,
+        expiresAt,
+        maxAttempts,
+    });
+    return { code, expiresAt };
+}
+/**
+ * Verify a submitted code. On success the record is deleted (codes
+ * are single-use). On mismatch the attempt counter is bumped; once
+ * `maxAttempts` is reached the record is wiped and the next call
+ * looks like "no code requested" — the user has to start over.
+ *
+ * Throws {@link AuthError} (`verification_failed`, HTTP 401) on any
+ * failure path so route handlers can surface a single error to the
+ * SPA without leaking which path was taken.
+ */
+export async function verifyVerificationCode(input) {
+    const record = await input.store.get({
+        channel: input.channel,
+        identifier: input.identifier,
+    });
+    if (!record) {
+        throw new AuthError('verification_failed', 'No verification code outstanding — request a new one', 401);
+    }
+    if (record.expiresAt < Date.now()) {
+        await input.store.delete({
+            channel: input.channel,
+            identifier: input.identifier,
+        });
+        throw new AuthError('verification_failed', 'Verification code expired — request a new one', 401);
+    }
+    const submittedHash = hashVerificationCode(input.code);
+    const a = Buffer.from(submittedHash, 'hex');
+    const b = Buffer.from(record.codeHash, 'hex');
+    const matches = a.length === b.length && timingSafeEqual(a, b);
+    if (matches) {
+        await input.store.delete({
+            channel: input.channel,
+            identifier: input.identifier,
+        });
+        return;
+    }
+    // Wrong code — bump the counter; if we've hit the limit, wipe the
+    // record so the user has to request a new one (this is the
+    // brute-force defense, since 6-digit codes only have 1M states).
+    const attempts = await input.store.incrementAttempts({
+        channel: input.channel,
+        identifier: input.identifier,
+    });
+    if (attempts >= record.maxAttempts) {
+        await input.store.delete({
+            channel: input.channel,
+            identifier: input.identifier,
+        });
+    }
+    throw new AuthError('verification_failed', 'Invalid verification code', 401);
+}
+// ────────────────────────────────────────────────────────────────────
+// In-memory store — for tests / local dev only
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Process-local store. Useful in unit tests and local `vk dev` runs
+ * (single Lambda warm container); never use in production — codes
+ * vanish on cold start, and parallel containers don't see each
+ * other's records.
+ */
+export function createInMemoryVerificationCodeStore() {
+    const map = new Map();
+    const key = (c, i) => `${c}\u0000${i}`;
+    return {
+        async put({ channel, identifier, codeHash, expiresAt, maxAttempts }) {
+            map.set(key(channel, identifier), {
+                channel,
+                identifier,
+                codeHash,
+                expiresAt,
+                attempts: 0,
+                maxAttempts,
+            });
+        },
+        async get({ channel, identifier }) {
+            return map.get(key(channel, identifier));
+        },
+        async incrementAttempts({ channel, identifier }) {
+            const rec = map.get(key(channel, identifier));
+            if (!rec)
+                return 0;
+            rec.attempts += 1;
+            return rec.attempts;
+        },
+        async delete({ channel, identifier }) {
+            map.delete(key(channel, identifier));
+        },
+    };
+}
+//# sourceMappingURL=verification.js.map

package/dist/server/verification.js.map

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

package/migrations/vk_auth_001_verification_codes.sql

@@ -0,0 +1,52 @@
+-- vk_auth_001_verification_codes.sql
+--
+-- Owned by `@venturekit/auth`. Backs `VerificationCodeStore` (used by
+-- the OTP gating on self-service sign-up + sign-in / passwordless).
+--
+-- Rows are pre-Cognito state — created BEFORE a user exists in either
+-- Cognito or any consumer-side `users` mirror. The `identifier` is the
+-- email or E.164 phone number the code was sent to; `channel` is the
+-- delivery surface.
+--
+-- Storage shape:
+--   - `code_hash` is SHA-256 of the plaintext code (hex). Plaintext
+--     never lands in the DB so a future leak still requires brute
+--     force against the (short) TTL.
+--   - `expires_at` is the wall-clock cutoff after which the
+--     `verifyVerificationCode` helper deletes the row and surfaces
+--     `verification_failed`.
+--   - `attempts` is incremented on every wrong-code submission;
+--     once it reaches `max_attempts` the row is deleted (forces the
+--     user to request a fresh code).
+--
+-- Channel typing: stored as TEXT + CHECK rather than a Postgres enum
+-- so this migration does not depend on `@venturekit/notify`'s
+-- `notify_channel` enum (auth must be usable without notify — e.g. a
+-- project that ships its own delivery layer). Add new values here when
+-- the auth package learns to dispatch over them.
+--
+-- Idempotent: uses `CREATE TABLE IF NOT EXISTS` so projects that
+-- previously created the table from their own migration (with a
+-- compatible shape) can adopt this one without dropping data. The
+-- expectation is that those projects will then leave their old
+-- migration file in place but stop hand-maintaining the schema here.
+
+CREATE TABLE IF NOT EXISTS verification_codes (
+  channel       TEXT        NOT NULL,
+  identifier    TEXT        NOT NULL,
+  code_hash     TEXT        NOT NULL,
+  expires_at    TIMESTAMPTZ NOT NULL,
+  attempts      INT         NOT NULL DEFAULT 0,
+  max_attempts  INT         NOT NULL DEFAULT 5,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (channel, identifier),
+  CONSTRAINT verification_codes_channel_chk
+    CHECK (channel IN ('email', 'whatsapp', 'sms')),
+  CONSTRAINT verification_codes_attempts_chk
+    CHECK (attempts >= 0),
+  CONSTRAINT verification_codes_max_attempts_chk
+    CHECK (max_attempts >= 1)
+);
+
+CREATE INDEX IF NOT EXISTS idx_verification_codes_expires_at
+  ON verification_codes (expires_at);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@venturekit/auth",
-  "version": "0.0.0-dev.20260507015944",
+  "version": "0.0.0-dev.20260511023410",
   "description": "Authentication and authorization for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "migrations"
   ],
   "repository": {
     "type": "git",
@@ -18,6 +19,9 @@
     "access": "public"
   },
   "license": "Apache-2.0",
+  "vk": {
+    "migrations": "migrations"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -29,12 +33,13 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.0-dev.20260507015944",
+    "@venturekit/core": "0.0.0-dev.20260511023410",
     "@aws-sdk/client-cognito-identity-provider": "^3.668.0",
+    "@aws-sdk/client-secrets-manager": "^3.668.0",
     "aws-jwt-verify": "^4.0.1"
   },
   "peerDependencies": {
-    "@venturekit/runtime": "0.0.0-dev.20260507015944"
+    "@venturekit/runtime": "0.0.0-dev.20260511023410"
   },
   "peerDependenciesMeta": {
     "@venturekit/runtime": {
@@ -42,7 +47,7 @@
     }
   },
   "devDependencies": {
-    "@venturekit/runtime": "0.0.0-dev.20260507015944",
+    "@venturekit/runtime": "0.0.0-dev.20260511023410",
     "@types/aws-lambda": "^8.10.131",
     "@types/node": "^25.6.0",
     "typescript": "^5.3.0"