@camstack/server 1.1.51 → 1.1.53

package/dist/api/core/auth.router.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXCHANGE_SESSION_HEADER = void 0;
 exports.createAuthRouter = createAuthRouter;
 /**
  * Auth router — core API for login/logout/me.
@@ -20,6 +21,8 @@ const zod_1 = require("zod");
 const server_1 = require("@trpc/server");
 const types_1 = require("@camstack/types");
 const share_token_service_js_1 = require("../../core/auth/share-token.service.js");
+const handoff_code_service_js_1 = require("../../core/auth/handoff-code.service.js");
+const session_cookie_js_1 = require("../../auth/session-cookie.js");
 const trpc_middleware_js_1 = require("../trpc/trpc.middleware.js");
 /**
  * The available second-factor kinds a user may satisfy after the
@@ -74,6 +77,8 @@ const FinishDiscoverableAuthenticationSchema = zod_1.z.object({
     userId: zod_1.z.string().nullable(),
 });
 const RemovePasskeySchema = zod_1.z.object({ success: zod_1.z.literal(true) });
+const SecondFactorPreferenceSchema = zod_1.z.object({ enabled: zod_1.z.boolean() });
+const SetSecondFactorPreferenceSchema = zod_1.z.object({ success: zod_1.z.literal(true) });
 function proxyPasskeyProvider(proxy) {
     const call = async (method, params) => {
         const fn = proxy[method];
@@ -90,6 +95,8 @@ function proxyPasskeyProvider(proxy) {
         finishDiscoverableAuthentication: async (input) => FinishDiscoverableAuthenticationSchema.parse(await call('finishDiscoverableAuthentication', input)),
         listPasskeys: async (input) => zod_1.z.array(types_1.PasskeySummarySchema).parse(await call('listPasskeys', input)),
         removePasskey: async (input) => RemovePasskeySchema.parse(await call('removePasskey', input)),
+        getSecondFactorPreference: async (input) => SecondFactorPreferenceSchema.parse(await call('getSecondFactorPreference', input)),
+        setSecondFactorPreference: async (input) => SetSecondFactorPreferenceSchema.parse(await call('setSecondFactorPreference', input)),
     };
 }
 function resolvePasskeyProvider(registry, moleculer) {
@@ -115,6 +122,26 @@ async function userHasPasskey(userId, provider) {
         return false;
     }
 }
+/**
+ * Whether the user OPTED IN to their passkey doubling as a mandatory
+ * second factor after a password login. Enrolling a passkey alone only
+ * enables passkey-FIRST sign-in — this flag (default OFF, stored by the
+ * `user-passkeys` provider) is what re-arms the 2FA gate. Never throws:
+ * a missing provider, a provider predating the method, or a transport
+ * hiccup all read as `false` so the preference lookup can never lock a
+ * user out of the password flow.
+ */
+async function passkeySecondFactorOptedIn(userId, provider) {
+    if (!provider || typeof provider.getSecondFactorPreference !== 'function')
+        return false;
+    try {
+        const pref = await provider.getSecondFactorPreference({ userId });
+        return pref.enabled;
+    }
+    catch {
+        return false;
+    }
+}
 // ── Login-method aggregation (login-method cap) ──────────────────────
 //
 // The PUBLIC `listLoginMethods` procedure walks the `login-method`
@@ -175,19 +202,40 @@ function toShareTokenSummary(record) {
     };
 }
 /**
- * Share-token management is for REAL user sessions only. Scoped API
- * tokens (`cst_*`) and share-view principals (`csv_*`) must never mint,
- * list, or revoke share links — a leaked restricted token would
- * otherwise be able to widen its own reach.
+ * Token minting/management surfaces are for REAL user sessions only.
+ * Scoped API tokens (`cst_*`) and share-view principals (`csv_*`) must
+ * never mint, list, or revoke share links — nor mint handoff codes —
+ * a leaked restricted token would otherwise widen its own reach.
  */
-function assertRealUserSession(user) {
+function assertRealUserSession(user, what = 'Share-token management') {
     if (user.isScoped || user.shareView) {
         throw new server_1.TRPCError({
             code: 'FORBIDDEN',
-            message: 'Share-token management requires a real user session',
+            message: `${what} requires a real user session`,
         });
     }
 }
+// ── Session exchange (viewer same-origin session reuse) ──────────────
+//
+// The viewer web build is served by the hub under `/viewer/camstack/`
+// — SAME ORIGIN as the admin-ui. After an admin-ui login the session
+// JWT is mirrored into the httpOnly `camstack_session` cookie
+// (`POST /api/auth/session`); `auth.exchangeSession` lets the viewer
+// upgrade that cookie back into a bearer token WITHOUT ever reading the
+// cookie from JS (it's httpOnly — the browser attaches it, the server
+// answers with a freshly-minted session).
+/** Custom header a cross-site form can never set — CSRF gate for the
+ *  cookie-authenticated `exchangeSession` mutation. */
+exports.EXCHANGE_SESSION_HEADER = 'x-camstack-exchange';
+/** Read a single-valued request header off the tRPC context request. */
+function readRequestHeader(req, name) {
+    const value = req?.headers[name];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return null;
+}
 /** Wire shape of the authenticated user returned by `auth.me`. */
 const MeSchema = zod_1.z
     .object({
@@ -203,7 +251,7 @@ const MeSchema = zod_1.z
     agentId: zod_1.z.string().optional(),
 })
     .nullable();
-function createAuthRouter(auth, registry, moleculer = null, shareTokens = null) {
+function createAuthRouter(auth, registry, moleculer = null, shareTokens = null, handoffCodes = new handoff_code_service_js_1.HandoffCodeService()) {
     const requireShareTokens = () => {
         if (!shareTokens) {
             throw new Error('Share tokens unavailable — service not wired on this node');
@@ -217,7 +265,12 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
      * scopes / allowedDevices reflect any admin change made mid-flow —
      * signing from stale claims could mint a stale-scope session.
      */
-    const mintSessionForUserId = async (userId) => {
+    /**
+     * Fresh user record for `userId` via `user-management` — shared by the
+     * session-mint tail and the second-factor challenge legs (both need
+     * live identity claims, never stale ones).
+     */
+    const findUserById = async (userId) => {
         const userMgmt = registry?.getSingleton('user-management');
         if (!userMgmt) {
             throw new Error('Login unavailable — `user-management` capability not registered');
@@ -228,6 +281,10 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
         if (!fresh) {
             throw new Error('User no longer exists');
         }
+        return fresh;
+    };
+    const mintSessionForUserId = async (userId) => {
+        const fresh = await findUserById(userId);
         const sessionToken = auth.signToken({
             userId: fresh.id,
             username: fresh.username,
@@ -242,6 +299,57 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
             requiresTotp: false,
         };
     };
+    /**
+     * `mintSessionForUserId` with the "user vanished" failure mapped to a
+     * clean 401 — for the token-exchange legs (`exchangeSession`,
+     * `redeemHandoffCode`) where the caller presented a credential whose
+     * backing user may have been deleted mid-flight. Infrastructure
+     * failures (user-management cap not registered) still surface as 500.
+     */
+    const mintSessionOrUnauthorized = async (userId) => {
+        try {
+            return await mintSessionForUserId(userId);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'User no longer exists') {
+                throw new server_1.TRPCError({ code: 'UNAUTHORIZED', message: 'User no longer exists' });
+            }
+            throw error;
+        }
+    };
+    /**
+     * The second factors `userId` must still satisfy after a successful
+     * PRIMARY factor. 2FA applies uniformly to every primary method:
+     *
+     *   • `totp` — whenever enrolled, regardless of how the user signed in.
+     *   • `passkey` — ONLY when the user both has an enrolled passkey AND
+     *     explicitly opted in (`getSecondFactorPreference`, default OFF —
+     *     enrolling a passkey alone just enables passkey-first sign-in),
+     *     and NEVER when the primary factor already WAS the passkey
+     *     (re-proving the factor that just signed in adds nothing).
+     *
+     * Passkey introspection is resilient (missing provider / transport
+     * error ⇒ no passkey factor) so it can never block a login; a TOTP
+     * status failure still propagates — fail-open there would silently
+     * skip an enrolled factor.
+     */
+    const collectSecondFactors = async (userId, primary) => {
+        const userMgmt = registry?.getSingleton('user-management');
+        const totpStatus = userMgmt && typeof userMgmt.getTotpStatus === 'function'
+            ? await userMgmt.getTotpStatus({ userId })
+            : { enabled: false };
+        const factors = [];
+        if (totpStatus.enabled)
+            factors.push('totp');
+        if (primary !== 'passkey') {
+            const provider = resolvePasskeyProvider(registry, moleculer);
+            const enrolled = await userHasPasskey(userId, provider);
+            if (enrolled && (await passkeySecondFactorOptedIn(userId, provider))) {
+                factors.push('passkey');
+            }
+        }
+        return factors;
+    };
     return (0, trpc_middleware_js_1.trpcRouter)({
         login: trpc_middleware_js_1.publicProcedure
             .input(zod_1.z.object({ username: zod_1.z.string(), password: zod_1.z.string() }))
@@ -265,23 +373,17 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
             if (!user)
                 throw new Error('Invalid credentials');
             // ── Second-factor gate ───────────────────────────────────────
-            // After credentials validate, check every enrolled second
-            // factor. If ANY is present, mint a SHORT-LIVED challenge token
-            // instead of the real session — the client must complete one
-            // factor before we hand out the actual JWT. The challenge token
-            // carries `kind: 'totp-challenge'` so it can't be replayed
-            // against protected endpoints (the auth middleware rejects
-            // anything without the standard session shape); the same token
-            // binds both the TOTP and the passkey second legs (same userId).
-            const totpStatus = typeof userMgmt.getTotpStatus === 'function'
-                ? await userMgmt.getTotpStatus({ userId: user.id })
-                : { enabled: false };
-            const passkeyEnrolled = await userHasPasskey(user.id, resolvePasskeyProvider(registry, moleculer));
-            const secondFactors = [];
-            if (totpStatus.enabled)
-                secondFactors.push('totp');
-            if (passkeyEnrolled)
-                secondFactors.push('passkey');
+            // After credentials validate, collect every ACTIVE second
+            // factor (TOTP when enrolled; passkey only when enrolled AND
+            // the user opted in — see `collectSecondFactors`). If ANY is
+            // present, mint a SHORT-LIVED challenge token instead of the
+            // real session — the client must complete one factor before we
+            // hand out the actual JWT. The challenge token carries
+            // `kind: 'totp-challenge'` so it can't be replayed against
+            // protected endpoints (the auth middleware rejects anything
+            // without the standard session shape); the same token binds
+            // both the TOTP and the passkey second legs (same userId).
+            const secondFactors = await collectSecondFactors(user.id, 'password');
             if (secondFactors.length > 0) {
                 const challengeToken = auth.signTotpChallengeToken({
                     userId: user.id,
@@ -291,7 +393,7 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
                 return {
                     token: challengeToken,
                     user: { id: user.id, username: user.username, isAdmin: user.isAdmin },
-                    requiresTotp: totpStatus.enabled,
+                    requiresTotp: secondFactors.includes('totp'),
                     secondFactors,
                 };
             }
@@ -425,9 +527,12 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
          * `auth.login` mints — via the shared `mintSessionForUserId` tail
          * (fresh user re-fetch for up-to-date scopes).
          *
-         * NO second-factor bounce: a discoverable passkey assertion with
-         * user verification is already a strong (possession + inherence/
-         * knowledge) factor — enrolled TOTP is irrelevant on this path.
+         * Second-factor gate — SAME rules as `auth.login`: 2FA applies
+         * uniformly after any primary method, so an enrolled TOTP bounces
+         * this leg to the challenge stage (same challenge-token LoginResult
+         * shape, completed via `loginVerifyTotp`). The passkey factor
+         * itself is skipped here — the primary factor WAS the passkey, and
+         * re-proving it adds nothing.
          */
         passkeyLoginFinish: trpc_middleware_js_1.publicProcedure
             .input(zod_1.z.object({ response: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()) }))
@@ -442,8 +547,111 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
             if (!result.verified || !result.userId) {
                 throw new server_1.TRPCError({ code: 'UNAUTHORIZED', message: 'Passkey verification failed' });
             }
+            const secondFactors = await collectSecondFactors(result.userId, 'passkey');
+            if (secondFactors.length > 0) {
+                const challenged = await findUserById(result.userId);
+                const challengeToken = auth.signTotpChallengeToken({
+                    userId: challenged.id,
+                    username: challenged.username,
+                    isAdmin: challenged.isAdmin,
+                });
+                return {
+                    token: challengeToken,
+                    user: {
+                        id: challenged.id,
+                        username: challenged.username,
+                        isAdmin: challenged.isAdmin,
+                    },
+                    requiresTotp: secondFactors.includes('totp'),
+                    secondFactors,
+                };
+            }
             return mintSessionForUserId(result.userId);
         }),
+        /**
+         * PUBLIC — upgrade the browser's httpOnly session COOKIE into a
+         * bearer token (viewer same-origin session reuse). Authentication
+         * comes from the `camstack_session` cookie ONLY — never from a
+         * bearer header — so a hub-served SPA (the viewer under
+         * `/viewer/camstack/`) can bootstrap without its own login.
+         *
+         * Security properties:
+         *   • CSRF: mutation (POST) + a REQUIRED custom header
+         *     (`x-camstack-exchange: 1`) that a cross-site form can't set;
+         *     belt-and-braces on top of the cookie's `SameSite=Lax`
+         *     semantics (see `buildSessionCookie` — Lax already withholds
+         *     the cookie from cross-site POSTs).
+         *   • Only REAL session JWTs qualify: bridge tokens (`kind:
+         *     'totp-challenge'` / `'sso-bridge'`) and `cst_`/`csv_` opaque
+         *     tokens are rejected — the cookie must carry a v2 session.
+         *   • The returned bearer is minted FRESH through the shared
+         *     `mintSessionForUserId` tail (re-fetched user → up-to-date
+         *     scopes), equivalent to what `auth.login` hands out.
+         */
+        exchangeSession: trpc_middleware_js_1.publicProcedure
+            .input(zod_1.z.object({}).optional())
+            .output(LoginResultSchema)
+            .mutation(async ({ ctx }) => {
+            if (readRequestHeader(ctx.req, exports.EXCHANGE_SESSION_HEADER) !== '1') {
+                throw new server_1.TRPCError({
+                    code: 'FORBIDDEN',
+                    message: `Missing ${exports.EXCHANGE_SESSION_HEADER} header`,
+                });
+            }
+            const cookieToken = (0, session_cookie_js_1.readSessionCookieFromHeader)(readRequestHeader(ctx.req, 'cookie') ?? undefined);
+            if (!cookieToken) {
+                throw new server_1.TRPCError({ code: 'UNAUTHORIZED', message: 'No session cookie' });
+            }
+            let payload;
+            try {
+                payload = auth.verifyToken(cookieToken);
+            }
+            catch {
+                throw new server_1.TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid session cookie' });
+            }
+            // Reject non-session JWTs that verify under the same secret:
+            // challenge/bridge tokens carry a `kind` discriminator, and a
+            // v2 session always has a boolean `isAdmin` + string `userId`.
+            const kind = Reflect.get(payload, 'kind');
+            if (kind !== undefined ||
+                typeof payload.isAdmin !== 'boolean' ||
+                typeof payload.userId !== 'string') {
+                throw new server_1.TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid session cookie' });
+            }
+            return mintSessionOrUnauthorized(payload.userId);
+        }),
+        // ── One-time handoff codes (native-app login handoff) ─────────────
+        //
+        // The admin-ui login page, when its `redirect` param is the app's
+        // custom-scheme callback, mints a code AFTER a successful login and
+        // bounces to `camstack://auth-callback?code=…`; the app redeems it
+        // for a real session. TTL 60s, single-use, bound to the minting
+        // user — see `HandoffCodeService`.
+        /** Mint a one-time handoff code for the CALLING user. Real user
+         *  sessions only — scoped (`cst_`) and share-view (`csv_`) callers
+         *  must never convert themselves into a full session. */
+        createHandoffCode: trpc_middleware_js_1.protectedProcedure
+            .input(zod_1.z.void())
+            .output(zod_1.z.object({ code: zod_1.z.string(), expiresAt: zod_1.z.number() }))
+            .mutation(({ ctx }) => {
+            assertRealUserSession(ctx.user, 'Handoff-code minting');
+            return handoffCodes.create(ctx.user.id);
+        }),
+        /** PUBLIC — redeem a one-time handoff code for a session bearer.
+         *  Unknown / expired / already-used codes → UNAUTHORIZED. */
+        redeemHandoffCode: trpc_middleware_js_1.publicProcedure
+            .input(zod_1.z.object({ code: zod_1.z.string().min(1) }))
+            .output(LoginResultSchema)
+            .mutation(async ({ input }) => {
+            const grant = handoffCodes.redeem(input.code);
+            if (!grant) {
+                throw new server_1.TRPCError({
+                    code: 'UNAUTHORIZED',
+                    message: 'Invalid or expired handoff code',
+                });
+            }
+            return mintSessionOrUnauthorized(grant.userId);
+        }),
         me: trpc_middleware_js_1.protectedProcedure
             .input(zod_1.z.void())
             .output(MeSchema)
@@ -587,6 +795,44 @@ function createAuthRouter(auth, registry, moleculer = null, shareTokens = null)
                 throw new Error('Passkey management is not available');
             return provider.removePasskey({ userId: ctx.user.id, credentialId: input.credentialId });
         }),
+        /**
+         * Own passkey second-factor preference (opt-in, default OFF).
+         * Enrolling a passkey only enables passkey-first sign-in; flipping
+         * this on additionally demands the passkey as a second factor after
+         * every password login. Bound to `ctx.user.id` like the rest of the
+         * self-service block; reads degrade to `enabled: false` so the "My
+         * access" page renders even while the provider is booting.
+         */
+        getOwnPasskeySecondFactorPreference: trpc_middleware_js_1.protectedProcedure
+            .input(zod_1.z.void())
+            .output(SecondFactorPreferenceSchema)
+            .query(async ({ ctx }) => {
+            if (!ctx.user)
+                return { enabled: false };
+            const provider = resolvePasskeyProvider(registry, moleculer);
+            if (!provider)
+                return { enabled: false };
+            try {
+                return await provider.getSecondFactorPreference({ userId: ctx.user.id });
+            }
+            catch {
+                return { enabled: false };
+            }
+        }),
+        setOwnPasskeySecondFactorPreference: trpc_middleware_js_1.protectedProcedure
+            .input(zod_1.z.object({ enabled: zod_1.z.boolean() }))
+            .output(SetSecondFactorPreferenceSchema)
+            .mutation(async ({ input, ctx }) => {
+            if (!ctx.user)
+                throw new Error('Not authenticated');
+            const provider = resolvePasskeyProvider(registry, moleculer);
+            if (!provider)
+                throw new Error('Passkey management is not available');
+            return provider.setSecondFactorPreference({
+                userId: ctx.user.id,
+                enabled: input.enabled,
+            });
+        }),
         // ── Share tokens — scoped, TTL'd view tokens for standalone share
         //    links (grid rework R6). Minted by any REAL user session (admin
         //    or regular); the resulting `csv_*` token authenticates as a

package/dist/api/trpc/generated-cap-routers.js

@@ -7559,6 +7559,24 @@ function createCapRouter_userPasskeys(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.removePasskey(methodInput);
         }),
+        getSecondFactorPreference: trpc_middleware_js_1.adminProcedure
+            .input(types_105.userPasskeysCapability.methods.getSecondFactorPreference.input.loose())
+            .output(types_105.userPasskeysCapability.methods.getSecondFactorPreference.output)
+            .query(async ({ input, ctx }) => {
+            const { nodeId, addonId, ...methodInput } = input;
+            const p = resolveProvider('user-passkeys', nodeId, () => getProvider(ctx, addonId), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.getSecondFactorPreference(methodInput);
+        }),
+        setSecondFactorPreference: trpc_middleware_js_1.adminProcedure
+            .input(types_105.userPasskeysCapability.methods.setSecondFactorPreference.input.loose())
+            .output(types_105.userPasskeysCapability.methods.setSecondFactorPreference.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, addonId, ...methodInput } = input;
+            const p = resolveProvider('user-passkeys', nodeId, () => getProvider(ctx, addonId), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.setSecondFactorPreference(methodInput);
+        }),
     });
 }
 function createCapRouter_vacuumControl(getProvider, createRemoteProxy) {

package/dist/api/trpc/trpc.router.js

@@ -166,7 +166,7 @@ function buildCapabilityRouters(services) {
         // clusterNodes — fixed core API. Write-side purge for the durable
         // offline-node history (Track A "Forget node"); read side is push-only.
         clusterNodes: (0, cluster_nodes_router_js_1.createClusterNodesRouter)(services.agentRegistry),
-        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry, services.moleculer, services.shareTokenService),
+        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry, services.moleculer, services.shareTokenService, services.handoffCodeService),
         // NOT MOUNTED — `mount: { kind: 'skip' }` legacy provider shapes
         // (positional args / sync returns) that don't match the codegen
         // routers' {input}-object + Promise<T> contract. The runtime builder

package/dist/auth/session-cookie.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SESSION_COOKIE = void 0;
 exports.buildSessionCookie = buildSessionCookie;
 exports.clearSessionCookie = clearSessionCookie;
+exports.readSessionCookieFromHeader = readSessionCookieFromHeader;
 exports.shouldRedirectToLogin = shouldRedirectToLogin;
 exports.loginRedirectUrl = loginRedirectUrl;
 exports.isEmbedRedirectTarget = isEmbedRedirectTarget;
+exports.isSessionGradeJwtPayload = isSessionGradeJwtPayload;
 /** Browser session cookie carrying the hub JWT. Set by POST /api/auth/session
  *  after a tRPC login; read by the addon-route catch-all for `authenticated`
  *  routes hit by a plain browser navigation. */
@@ -24,6 +26,34 @@ function clearSessionCookie() {
         options: { httpOnly: true, sameSite: 'lax', secure: true, path: '/', maxAge: 0 },
     };
 }
+/**
+ * Extract the session JWT from a raw `Cookie` request header. Plugin-free
+ * (works on both Fastify requests and bare WS upgrade `IncomingMessage`s)
+ * so callers don't depend on `@fastify/cookie` decoration order. Returns
+ * `null` when the header is absent or carries no `camstack_session` pair.
+ */
+function readSessionCookieFromHeader(header) {
+    if (!header)
+        return null;
+    for (const pair of header.split(';')) {
+        const eq = pair.indexOf('=');
+        if (eq === -1)
+            continue;
+        const name = pair.slice(0, eq).trim();
+        if (name !== exports.SESSION_COOKIE)
+            continue;
+        const raw = pair.slice(eq + 1).trim();
+        if (raw === '')
+            return null;
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return null;
+}
 /** A browser navigation we can bounce to the login page: a top-level GET
  *  that wants HTML. Anything else (API call, POST, non-HTML) keeps the
  *  401 behavior so programmatic clients get a clean error. */
@@ -45,3 +75,17 @@ function isEmbedRedirectTarget(next) {
         return false;
     return true;
 }
+/**
+ * True only for a payload with the v2 SESSION shape: string `userId`,
+ * boolean `isAdmin`, and NO `kind` discriminator. Challenge/bridge tokens
+ * (`kind: 'totp-challenge' | 'sso-bridge'`) verify under the same hub
+ * secret but are NOT sessions — accepting one as a session cookie lets a
+ * password-only attacker skip the second factor on every cookie-gated
+ * surface. Shared by `POST /api/auth/session` and `auth.exchangeSession`.
+ */
+function isSessionGradeJwtPayload(payload) {
+    if (payload === null || typeof payload !== 'object')
+        return false;
+    const p = payload;
+    return p.kind === undefined && typeof p.userId === 'string' && typeof p.isAdmin === 'boolean';
+}

package/dist/core/auth/handoff-code.service.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandoffCodeService = exports.HANDOFF_CODE_MAX_PENDING = exports.HANDOFF_CODE_TTL_MS = exports.HANDOFF_CODE_PREFIX = void 0;
+/**
+ * HandoffCodeService — one-time login handoff codes for the native-app
+ * auth handoff (viewer "Sign in with CamStack").
+ *
+ * Flow: an AUTHENTICATED browser session (the admin-ui login page, after
+ * any successful login leg) mints a short-lived single-use code bound to
+ * its user, then bounces to the app's custom-scheme callback
+ * (`camstack://auth-callback?code=…`). The app redeems the code over the
+ * PUBLIC `auth.redeemHandoffCode` procedure and receives a real session
+ * JWT minted through the same `mintSessionForUserId` tail every login
+ * leg uses.
+ *
+ * Design mirrors the pending-challenge / share-token patterns:
+ *   • the raw code is returned exactly once; only its SHA-256 hash is
+ *     kept server-side, so a memory dump never exposes redeemable codes;
+ *   • TTL 60s — long enough to survive the browser → app bounce, short
+ *     enough that a leaked callback URL goes stale before it travels;
+ *   • single-use — the entry is consumed on FIRST redeem attempt
+ *     (even an expired hit is deleted), so a replayed code is dead;
+ *   • in-memory only — codes never need to survive a hub restart
+ *     (the browser just re-runs the handoff), and a bounded store +
+ *     prune-on-mint keeps the map from growing.
+ */
+const crypto = __importStar(require("node:crypto"));
+/** Wire prefix — `chc_` = CamStack Handoff Code (cf. `cst_`/`csv_`). */
+exports.HANDOFF_CODE_PREFIX = 'chc_';
+exports.HANDOFF_CODE_TTL_MS = 60_000;
+/** Hard bound on concurrently-pending codes (mint is auth-gated, so this
+ *  only guards against a runaway authenticated client). */
+exports.HANDOFF_CODE_MAX_PENDING = 1_000;
+function hashCode(code) {
+    return crypto.createHash('sha256').update(code).digest('hex');
+}
+class HandoffCodeService {
+    now;
+    ttlMs;
+    /** Keyed by SHA-256(raw code). */
+    pending = new Map();
+    constructor(now = Date.now, ttlMs = exports.HANDOFF_CODE_TTL_MS) {
+        this.now = now;
+        this.ttlMs = ttlMs;
+    }
+    /** Mint a single-use code bound to `userId`. Throws when the pending
+     *  store is full even after pruning expired entries (fail fast — a
+     *  legitimate flow never has anywhere near this many in flight). */
+    create(userId) {
+        this.prune();
+        if (this.pending.size >= exports.HANDOFF_CODE_MAX_PENDING) {
+            throw new Error('Too many pending handoff codes — try again shortly');
+        }
+        const code = `${exports.HANDOFF_CODE_PREFIX}${crypto.randomBytes(32).toString('hex')}`;
+        const expiresAt = this.now() + this.ttlMs;
+        this.pending.set(hashCode(code), { userId, expiresAt });
+        return { code, expiresAt };
+    }
+    /** Redeem a raw code. Consumes the entry on the FIRST attempt no
+     *  matter the outcome (single-use); returns `null` for unknown,
+     *  already-used, or expired codes — the router maps that to 401. */
+    redeem(code) {
+        const entry = this.pending.get(hashCode(code));
+        if (!entry)
+            return null;
+        this.pending.delete(hashCode(code));
+        if (this.now() > entry.expiresAt)
+            return null;
+        return { userId: entry.userId };
+    }
+    /** Number of not-yet-redeemed (possibly expired) codes. Test/diag aid. */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    prune() {
+        const cutoff = this.now();
+        for (const [key, entry] of this.pending) {
+            if (cutoff > entry.expiresAt)
+                this.pending.delete(key);
+        }
+    }
+}
+exports.HandoffCodeService = HandoffCodeService;

package/dist/main.js

@@ -51,6 +51,7 @@ const event_bus_service_1 = require("./core/events/event-bus.service");
 const config_service_1 = require("./core/config/config.service");
 const auth_service_1 = require("./core/auth/auth.service");
 const share_token_service_1 = require("./core/auth/share-token.service");
+const handoff_code_service_1 = require("./core/auth/handoff-code.service");
 // Boot-time capability declaration runs over the auto-generated
 // `ALL_CAPABILITY_DEFINITIONS` array — every `*.cap.ts` file that ships
 // with `@camstack/types` is included automatically. Adding a new cap
@@ -353,9 +354,14 @@ async function bootstrap() {
         // the settings backend (lazy getter: the backend lands after the
         // sqlite-storage builtin registers; the service resolves it per call).
         const shareTokenService = new share_token_service_1.ShareTokenService(() => addonRegistry.getSettingsBackend(), loggingService.createLogger('share-tokens'));
+        // One-time native-app login handoff codes (in-memory, 60s TTL,
+        // single-use) — minted by `auth.createHandoffCode`, redeemed by the
+        // viewer app via the public `auth.redeemHandoffCode`.
+        const handoffCodeService = new handoff_code_service_1.HandoffCodeService();
         appRouter = (0, trpc_router_1.buildAppRouter)({
             authService,
             shareTokenService,
+            handoffCodeService,
             configService: config,
             featureService: app.get(feature_service_1.FeatureService),
             loggingService,
@@ -642,6 +648,13 @@ async function bootstrap() {
             let ttlSec;
             try {
                 const payload = authService.verifyToken(token); // throws on invalid/expired
+                // SESSION-grade JWTs only: challenge/bridge tokens (`kind`-tagged,
+                // e.g. the totp-challenge from login leg 1) verify under the same
+                // secret — accepting one here handed out a cookie that bypassed
+                // the second factor on every cookie-gated surface.
+                if (!(0, session_cookie_js_1.isSessionGradeJwtPayload)(payload)) {
+                    return reply.status(401).send({ error: 'invalid token' });
+                }
                 const expSec = typeof payload.exp === 'number' ? payload.exp : 0;
                 ttlSec = Math.max(0, expSec - Math.floor(Date.now() / 1000));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.1.51",
+  "version": "1.1.53",
   "private": false,
   "files": [
     "dist",
@@ -23,18 +23,18 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.1.43",
+    "@camstack/addon-admin-ui": "1.1.45",
     "@camstack/addon-advanced-notifier": "1.1.21",
-    "@camstack/addon-auth": "1.1.5",
+    "@camstack/addon-auth": "1.1.6",
     "@camstack/addon-decoder-nodeav": "1.1.9",
     "@camstack/addon-notifiers": "1.1.21",
     "@camstack/addon-pipeline": "1.1.51",
-    "@camstack/addon-pipeline-orchestrator": "1.1.38",
+    "@camstack/addon-pipeline-orchestrator": "1.1.39",
     "@camstack/addon-post-analysis": "1.1.23",
-    "@camstack/sdk": "1.1.21",
+    "@camstack/sdk": "1.1.22",
     "@camstack/shm-ring": "1.0.21",
-    "@camstack/system": "1.1.40",
-    "@camstack/types": "1.1.37",
+    "@camstack/system": "1.1.41",
+    "@camstack/types": "1.1.39",
     "@camstack/ui-library": "1.1.31",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",