@camstack/server 1.2.486 → 1.2.487

package/dist/api/trpc/trpc.context.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMeshTrpcContext = createMeshTrpcContext;
 exports.createTrpcContext = createTrpcContext;
 exports.createWsTrpcContext = createWsTrpcContext;
+const system_1 = require("@camstack/system");
 const types_1 = require("@camstack/types");
+const auth_network_policy_js_1 = require("../../auth/auth-network-policy.js");
 const share_token_service_js_1 = require("../../core/auth/share-token.service.js");
 const trpc_error_principal_js_1 = require("./trpc-error-principal.js");
 /**
@@ -86,20 +88,52 @@ function extractTokenFromRequest(req) {
     }
     return null;
 }
+function requestFacts(req) {
+    if (req === undefined)
+        return {};
+    const ip = auth_network_policy_js_1.DEFAULT_AUTH_NETWORK_POLICY.clientAddress(req).ip;
+    const url = req.url;
+    const path = typeof url === 'string' ? url.split('?')[0] : undefined;
+    return { ...(path !== undefined ? { path } : {}), ...(ip !== null ? { ip } : {}) };
+}
 /**
- * Resolve an AuthenticatedAgent from a raw token. Handles both JWT
- * (sync, via authService) and `cst_*` scoped tokens (async, via the
- * `user-management` cap singleton — same path addon-upload uses for
- * its REST auth chain).
- *
- * Returns `null` for: missing token, malformed JWT, unknown scoped
- * token, and a JWT that is not an ACCESS CREDENTIAL (see the classifier
- * branch below). Caller (protectedProcedure) decides the failure
- * response (typically UNAUTHORIZED).
+ * An admin token (`csa_`): an ADMIN principal, attributed to the admin who
+ * created it, every use audited. Validation (owner still exists and is still
+ * an admin, not revoked, not expired) is local-auth's (`AdminTokenManager`).
  */
-async function resolveUser(token, authService, addonRegistry, shareTokens = null, logger = null) {
+async function resolveAdminToken(token, addonRegistry, facts) {
+    const internal = (0, system_1.getUserManagementInternal)(addonRegistry.getCapabilityRegistry().getSingleton('user-management'));
+    if (internal === null)
+        return null;
+    const record = await internal.adminTokens.validate(token).catch(() => null);
+    if (record === null)
+        return null;
+    void internal.audit.record({
+        action: 'admin-token-used',
+        userId: record.createdBy,
+        ...(facts.ip !== undefined ? { ip: facts.ip } : {}),
+        detail: {
+            tokenId: record.id,
+            name: record.name,
+            prefix: record.tokenPrefix,
+            ...(facts.path !== undefined ? { path: facts.path } : {}),
+        },
+    });
+    return {
+        id: record.createdBy,
+        username: `admin-token:${record.name}`,
+        isAdmin: true,
+        permissions: { isAdmin: true, allowedProviders: '*', allowedDevices: {} },
+        isApiKey: true,
+        credential: 'admin-token',
+        adminTokenId: record.id,
+    };
+}
+async function resolveUser(token, authService, addonRegistry, shareTokens = null, logger = null, facts = {}) {
     if (!token)
         return null;
+    if (token.startsWith(system_1.ADMIN_TOKEN_PREFIX))
+        return resolveAdminToken(token, addonRegistry, facts);
     // Share-token path (`csv_*`): resolve through the ShareTokenService.
     // The synthetic principal is maximally restricted — non-admin, no
     // scopes; the `shareView` grant routes it into the fail-closed
@@ -183,16 +217,15 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
         // `verifyToken` succeeding means "we minted this", never "this is an API
         // credential" (D103). Exactly two kinds are credentials here:
         //
-        //   • `session` — no `kind` claim: `auth.login`'s JWT, the SSO-minted
-        //     session from `/api/auth/sso/finish`, a `type: 'service'` agent
-        //     token, a `type: 'api_key'` token.
+        //   • `session` — no `kind` claim: `auth.login`'s JWT and the SSO-minted
+        //     session from `/api/auth/sso/finish`.
         //   • `integration` — `provider: 'oauth-access'`: the account-link
         //     credential a component (Home Assistant) calls `/trpc` with.
         //
         // Everything else is minted for ONE hand-off step and is refused: an
         // `oauth-code` is single-use, lives 60s and travels in a browser redirect
         // URL (history, referrers, proxy logs); an `oauth-refresh` belongs to
-        // `POST /oauth/token`; an `oidc`/`magic-link` bridge belongs to
+        // `POST /oauth/token`; an `oidc` login bridge belongs to
         // `?bridge=` on `/api/auth/sso/finish`; a `totp-challenge` is login leg 1.
         // `/addon/:addonId/*` has refused these since D103 — this closes the same
         // hole on the other surface.
@@ -203,7 +236,7 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
         // `!requiresSecondFactor`) nor the admin UI ever puts it in a header.
         if (principal.kind === 'not-a-credential') {
             logger?.warn('trpc: refused a bearer that is not an API credential', {
-                meta: { reason: principal.reason, userId: payload.userId ?? payload.keyId ?? 'unknown' },
+                meta: { reason: principal.reason, userId: payload.userId ?? 'unknown' },
             });
             return null;
         }
@@ -212,7 +245,7 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
         // indistinguishable in the logs from a refusal of a browser session.
         const credential = (0, trpc_error_principal_js_1.readCredentialIdentity)(payload);
         return {
-            id: payload.userId ?? payload.keyId ?? 'unknown',
+            id: payload.userId ?? 'unknown',
             username: payload.username ?? 'unknown',
             isAdmin: payload.isAdmin,
             permissions: {
@@ -220,8 +253,10 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
                 allowedProviders: payload.allowedProviders,
                 allowedDevices: payload.allowedDevices,
             },
-            isApiKey: payload.type === 'api_key',
-            agentId: payload.agentId,
+            isApiKey: false,
+            ...(principal.kind === 'session' && typeof payload.sid === 'string'
+                ? { sessionId: payload.sid }
+                : {}),
             // Scopes are baked into the JWT at login; the middleware uses
             // them to gate every call until the user re-logs. Normalised at the
             // boundary — a v2 `device:targets` JWT (issued before the v3 model)
@@ -247,7 +282,7 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
             ...(payload.scopes !== undefined ? { scopes: (0, types_1.normalizeTokenScopes)(payload.scopes) } : {}),
             ...(!payload.isAdmin && principal.kind === 'session'
                 ? await (async () => {
-                    const fresh = await refreshScopesFromStore(payload.userId ?? payload.keyId ?? 'unknown', addonRegistry);
+                    const fresh = await refreshScopesFromStore(payload.userId ?? 'unknown', addonRegistry);
                     return fresh !== null ? { scopes: fresh } : {};
                 })()
                 : {}),
@@ -279,22 +314,27 @@ function makeDeviceScopeLookup(addonRegistry) {
     };
 }
 /**
- * Context factory for hub-internal calls originating from the trusted
- * Moleculer mesh (the `$core-caps` bridge service in `core-cap-bridge.ts`).
+ * Context factory for calls arriving over the Moleculer mesh (the `$core-caps`
+ * bridge service in `core-cap-bridge.ts`).
  *
- * A mesh-originated call is treated as a fully-trusted admin. NOTE (D797):
- * the cluster secret (System → Cluster) gates `$hub.registerNode` only — the
- * Moleculer TCP transport itself authenticates no peer, so anything that can
- * reach the hub's mesh port can call this. Keep that port off untrusted
- * networks; transport-level peer authentication is on the roadmap. It carries
- * a synthetic `isAdmin` user, which makes `protectedProcedure` /
- * `adminProcedure` pass without a JWT and skips the scope-access
- * matcher entirely. There is no HTTP request behind the call.
+ * `principal` names WHO is calling (D802): `mesh` for the hub's own runners
+ * (they reach the bridge over UDS, inside the hub's trust boundary), and
+ * `node:<nodeId>` for another node — whose id the hub's mesh gate has bound
+ * to a challenge–response proof before the call got here
+ * (`createMeshAccessMiddleware`; in `transition` mode an unauthenticated node
+ * is tolerated and its id is only what it claims).
+ *
+ * Both principals are still admins: that keeps every `adminProcedure` an
+ * agent's addons call working. What is NOT reachable from another node is
+ * decided by the bridge itself (`REMOTE_DENIED_NAMESPACES`), and `repl` is not
+ * bridged at all. Narrowing the remote principal to a per-method grant is the
+ * next step once the mesh census has measured what each node calls (D802).
+ * There is no HTTP request behind the call.
  */
-function createMeshTrpcContext() {
+function createMeshTrpcContext(principal = 'mesh') {
     const user = {
-        id: 'mesh',
-        username: 'mesh',
+        id: principal,
+        username: principal,
         isAdmin: true,
         permissions: { isAdmin: true, allowedProviders: '*', allowedDevices: {} },
         isApiKey: true,
@@ -305,7 +345,7 @@ function createMeshTrpcContext() {
 async function createTrpcContext(req, authService, addonRegistry, shareTokens = null, logger = null) {
     const token = extractTokenFromRequest(req);
     return {
-        user: await resolveUser(token, authService, addonRegistry, shareTokens, logger),
+        user: await resolveUser(token, authService, addonRegistry, shareTokens, logger, requestFacts(req)),
         req,
         deviceScopeLookup: makeDeviceScopeLookup(addonRegistry),
         deviceFleet: () => addonRegistry.getPersistedDeviceList(),
@@ -320,10 +360,22 @@ async function createWsTrpcContext(opts, authService, addonRegistry, shareTokens
     // 1. connectionParams.token (sent by BackendClient's createWSClient)
     const paramToken = opts.info.connectionParams?.['token'];
     const token = (typeof paramToken === 'string' ? paramToken : null) ?? extractTokenFromRequest(opts.req);
-    const user = await resolveUser(token, authService, addonRegistry, shareTokens, logger);
+    const user = await resolveUser(token, authService, addonRegistry, shareTokens, logger, requestFacts(opts.req));
+    const sessionId = user?.sessionId;
     return {
         user,
         req: opts.req,
+        ...(user !== null && sessionId !== undefined
+            ? {
+                sessionLive: () => authService.checkSession({
+                    sid: sessionId,
+                    userId: user.id,
+                    isAdmin: user.isAdmin,
+                    allowedProviders: '*',
+                    allowedDevices: {},
+                }) === null,
+            }
+            : {}),
         deviceScopeLookup: makeDeviceScopeLookup(addonRegistry),
         deviceFleet: () => addonRegistry.getPersistedDeviceList(),
     };

package/dist/api/trpc/trpc.middleware.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentProcedure = exports.adminProcedure = exports.protectedProcedure = exports.createCallerFactory = exports.publicProcedure = exports.trpcRouter = void 0;
+exports.adminProcedure = exports.protectedProcedure = exports.createCallerFactory = exports.publicProcedure = exports.trpcRouter = void 0;
 exports.iterableSubscription = iterableSubscription;
 exports.iterableInterval = iterableInterval;
 const system_1 = require("@camstack/system");
@@ -96,6 +96,12 @@ exports.protectedProcedure = t.procedure.use(async ({ ctx, next, path, getRawInp
     if (!ctx.user) {
         throw new server_1.TRPCError({ code: 'UNAUTHORIZED' });
     }
+    // A WebSocket resolves its principal once, at connect. Its login session is
+    // re-checked on every call, so a logout or revocation ends a socket that is
+    // already open — not only the next one.
+    if (ctx.sessionLive !== undefined && !ctx.sessionLive()) {
+        throw new server_1.TRPCError({ code: 'UNAUTHORIZED', message: 'Session ended — sign in again' });
+    }
     // Share-view principals (`csv_*` tokens) NEVER reach the admin bypass,
     // the hand-written-route pass-through, or the scope matcher below —
     // they are gated exclusively by the fail-closed embed-surface allowlist
@@ -133,7 +139,7 @@ exports.protectedProcedure = t.procedure.use(async ({ ctx, next, path, getRawInp
         return next({ ctx: { ...ctx, user: ctx.user } });
     }
     // Spread+reassign of `user` narrows downstream ctx from `User | null`
-    // to `User` so `adminProcedure` / `agentProcedure` can read fields
+    // to `User` so `adminProcedure` can read fields
     // without re-checking.
     if (ctx.user.isAdmin) {
         return next({ ctx: { ...ctx, user: ctx.user } });
@@ -199,12 +205,3 @@ exports.adminProcedure = exports.protectedProcedure.use(({ ctx, next }) => {
     }
     return next({ ctx });
 });
-/**
- * Procedure for agent service accounts. After the v2 collapse, agents
- * are admin sessions issued via `createServiceToken` — they all get
- * `isAdmin: true`. This procedure is identical to `adminProcedure`;
- * kept for naming clarity on agent-specific routes.
- */
-exports.agentProcedure = exports.adminProcedure.use(({ ctx, next }) => {
-    return next({ ctx: { ...ctx, agentId: ctx.user.agentId ?? ctx.user.id } });
-});

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

@@ -269,7 +269,12 @@ 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, services.handoffCodeService, services.externalLinkIntents),
+        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry, services.moleculer, services.shareTokenService, services.handoffCodeService, services.externalLinkIntents, services.nativeLink ?? null, {
+            ...(services.authNetworkPolicy !== undefined
+                ? { network: services.authNetworkPolicy }
+                : {}),
+            ...(services.sessionBacking !== undefined ? { sessions: services.sessionBacking } : {}),
+        }),
         // 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/auth-network-policy.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AUTH_NETWORK_POLICY = exports.TRUSTED_NETWORKS_KEY = exports.TRUSTED_PROXIES_KEY = void 0;
+exports.createAuthNetworkPolicy = createAuthNetworkPolicy;
+/**
+ * The two network facts the auth surface reads from settings:
+ *
+ *  - `auth.trustedProxies` — CIDRs whose forwarding headers are believed, on
+ *    top of loopback (`client-address.ts`);
+ *  - `auth.trustedNetworks` — CIDRs a login may skip its second factor from
+ *    (opt-in, empty = off). Only for a request made DIRECTLY from such a
+ *    network: anything that came through a proxy — the Cloudflare tunnel, the
+ *    public origin — never qualifies, whatever address it claims.
+ *
+ * Settings are read on every call (the hub's ConfigService answers from
+ * memory), so a change applies to the next request. A read the store cannot
+ * answer yet is treated as an EMPTY list: no extra proxy is trusted, and no
+ * network skips a factor — both fail closed.
+ */
+const system_1 = require("@camstack/system");
+const client_address_js_1 = require("./client-address.js");
+exports.TRUSTED_PROXIES_KEY = 'auth.trustedProxies';
+exports.TRUSTED_NETWORKS_KEY = 'auth.trustedNetworks';
+function asRequest(req) {
+    if (req === null || typeof req !== 'object')
+        return null;
+    const headers = Reflect.get(req, 'headers');
+    if (headers === null || typeof headers !== 'object')
+        return null;
+    const socket = Reflect.get(req, 'socket');
+    const remoteAddress = socket !== null && typeof socket === 'object' ? Reflect.get(socket, 'remoteAddress') : undefined;
+    return {
+        headers: Object.fromEntries(Object.entries(headers).filter((e) => typeof e[1] === 'string' || Array.isArray(e[1]))),
+        socket: { remoteAddress: typeof remoteAddress === 'string' ? remoteAddress : undefined },
+    };
+}
+function safeList(read, key) {
+    try {
+        return (0, system_1.readCidrSetting)(read(key));
+    }
+    catch {
+        return [];
+    }
+}
+/** One memo per list: rebuilding a BlockList per request is wasted work. */
+function memoMatcher() {
+    let lastKey = null;
+    let last = (0, system_1.createCidrMatcher)([]);
+    return (entries) => {
+        const key = entries.join('\n');
+        if (key !== lastKey) {
+            lastKey = key;
+            last = (0, system_1.createCidrMatcher)(entries);
+        }
+        return last;
+    };
+}
+function createAuthNetworkPolicy(read) {
+    const networks = memoMatcher();
+    return {
+        clientAddress(req) {
+            const request = asRequest(req);
+            if (request === null)
+                return { ip: null, peer: null, viaProxy: false };
+            return (0, client_address_js_1.resolveClientAddress)(request, { trustedProxies: safeList(read, exports.TRUSTED_PROXIES_KEY) });
+        },
+        isTrustedNetworkLogin(address) {
+            if (address.viaProxy || address.ip === null)
+                return false;
+            return networks(safeList(read, exports.TRUSTED_NETWORKS_KEY)).contains(address.ip);
+        },
+    };
+}
+/** No settings: loopback is the only trusted proxy, no network skips a factor. */
+exports.DEFAULT_AUTH_NETWORK_POLICY = createAuthNetworkPolicy(() => undefined);

package/dist/auth/auth-rate-limit.js

@@ -1,4 +1,7 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimiter = createRateLimiter;
+exports.clientKeyFromRequest = clientKeyFromRequest;
 /**
  * Public-auth rate limiting — fixed window per (bucket, client ip).
  *
@@ -13,9 +16,7 @@
  * BOUNDED (`maxKeys`, oldest-window evicted first) so an attacker
  * rotating spoofed source addresses cannot grow it without limit.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRateLimiter = createRateLimiter;
-exports.clientKeyFromRequest = clientKeyFromRequest;
+const auth_network_policy_js_1 = require("./auth-network-policy.js");
 function createRateLimiter(options) {
     const maxKeys = options.maxKeys ?? 10_000;
     const now = options.now ?? Date.now;
@@ -49,28 +50,32 @@ function createRateLimiter(options) {
             const retryAfterSeconds = Math.max(1, Math.ceil((existing.windowStart + options.windowMs - at) / 1000));
             return { allowed: false, retryAfterSeconds };
         },
+        peek(key) {
+            const at = now();
+            const existing = entries.get(key);
+            if (!existing || at - existing.windowStart >= options.windowMs) {
+                return { allowed: true, retryAfterSeconds: 0 };
+            }
+            if (existing.count < options.max)
+                return { allowed: true, retryAfterSeconds: 0 };
+            return {
+                allowed: false,
+                retryAfterSeconds: Math.max(1, Math.ceil((existing.windowStart + options.windowMs - at) / 1000)),
+            };
+        },
         size() {
             return entries.size;
         },
     };
 }
 /**
- * Client key for a tRPC/Fastify request principal: `FastifyRequest.ip`
- * (proxy-aware when Fastify's `trustProxy` is on) or the raw socket
- * address for WS-upgrade `IncomingMessage`s. `null` = no originating
- * request (mesh-internal `createCaller` invocation) — never limited.
+ * The rate-limit key of a request: its REAL client address — the forwarded
+ * client behind a trusted proxy (the tunnel connector on loopback, or
+ * `auth.trustedProxies`), else the socket peer (`auth-network-policy.ts`).
+ * Keyed on the raw peer, every tunnelled request shared `127.0.0.1` and one
+ * bucket locked the whole internet out. `null` = no originating request
+ * (a mesh-internal `createCaller`) — never limited.
  */
-function clientKeyFromRequest(req) {
-    if (req === null || typeof req !== 'object' || req === undefined)
-        return null;
-    const ip = Reflect.get(req, 'ip');
-    if (typeof ip === 'string' && ip.length > 0)
-        return ip;
-    const socket = Reflect.get(req, 'socket');
-    if (socket !== null && typeof socket === 'object') {
-        const remote = Reflect.get(socket, 'remoteAddress');
-        if (typeof remote === 'string' && remote.length > 0)
-            return remote;
-    }
-    return null;
+function clientKeyFromRequest(req, policy = auth_network_policy_js_1.DEFAULT_AUTH_NETWORK_POLICY) {
+    return policy.clientAddress(req).ip;
 }

package/dist/auth/client-address.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClientAddress = resolveClientAddress;
+/**
+ * The real client address of an HTTP / WS request.
+ *
+ * The hub is often published through a Cloudflare tunnel whose connector
+ * dials it on LOOPBACK, so the socket peer of every internet request is
+ * `127.0.0.1`. Fastify's `trustProxy` is off, so `req.ip` is that peer too.
+ * Keyed on it, every rate limiter shared one bucket among all remote users.
+ *
+ * The forwarding headers (`CF-Connecting-IP`, `X-Forwarded-For`) carry the
+ * real client — and are a plain claim from whoever sent them. They are read
+ * ONLY when the immediate peer is a proxy the hub trusts:
+ *
+ *  - loopback, always: the tunnel connector, or a proxy on the same host;
+ *  - the CIDRs the operator lists in `auth.trustedProxies` (a reverse proxy on
+ *    the LAN, the Home Assistant relay).
+ *
+ * From any other peer the headers are ignored and the peer IS the client — a
+ * LAN host is not a proxy, so it cannot claim another LAN address either.
+ *
+ * `viaProxy` says the request came through a trusted proxy at all. Anything
+ * that must hold only for a request made directly on the LAN (skipping the
+ * second factor from a trusted network) refuses `viaProxy` outright, whatever
+ * address the headers name.
+ */
+const system_1 = require("@camstack/system");
+const node_net_1 = require("node:net");
+const LOOPBACK = ['127.0.0.0/8', '::1/128'];
+function header(req, name) {
+    const raw = req.headers[name];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+function validIp(value) {
+    const ip = (0, system_1.normalizeIp)(value);
+    return (0, node_net_1.isIP)(ip) === 0 ? null : ip;
+}
+function resolveClientAddress(req, config) {
+    const rawPeer = req.socket?.remoteAddress;
+    const peer = typeof rawPeer === 'string' && rawPeer.length > 0 ? validIp(rawPeer) : null;
+    if (peer === null)
+        return { ip: null, peer: null, viaProxy: false };
+    const trusted = (0, system_1.createCidrMatcher)([...LOOPBACK, ...config.trustedProxies]);
+    if (!trusted.contains(peer))
+        return { ip: peer, peer, viaProxy: false };
+    // Cloudflare stamps the connecting client itself; prefer it when it parses.
+    const cf = header(req, 'cf-connecting-ip');
+    const cfIp = cf === null ? null : validIp(cf);
+    if (cfIp !== null)
+        return { ip: cfIp, peer, viaProxy: true };
+    // X-Forwarded-For: each proxy APPENDS the address it received from, so the
+    // right-most entry that is not itself a trusted proxy is the client. The
+    // left-most is whatever the client chose to send.
+    const xff = header(req, 'x-forwarded-for');
+    if (xff !== null) {
+        const hops = xff.split(',').map((h) => h.trim());
+        for (let i = hops.length - 1; i >= 0; i -= 1) {
+            const hop = validIp(hops[i] ?? '');
+            if (hop === null)
+                continue;
+            if (!trusted.contains(hop))
+                return { ip: hop, peer, viaProxy: true };
+        }
+    }
+    return { ip: peer, peer, viaProxy: true };
+}

package/dist/auth/external-link-intents.js

@@ -30,7 +30,7 @@ class ExternalLinkIntents {
         this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
         this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
     }
-    create(userId, provider) {
+    create(userId, provider, returnTo) {
         this.prune();
         while (this.intents.size >= this.maxEntries) {
             const oldest = this.intents.keys().next();
@@ -39,7 +39,12 @@ class ExternalLinkIntents {
             this.intents.delete(oldest.value);
         }
         const handle = `li_${(0, node_crypto_1.randomBytes)(24).toString('base64url')}`;
-        this.intents.set(handle, { userId, provider, expiresAt: this.now() + this.ttlMs });
+        this.intents.set(handle, {
+            userId,
+            provider,
+            ...(returnTo !== undefined ? { returnTo } : {}),
+            expiresAt: this.now() + this.ttlMs,
+        });
         return handle;
     }
     /** The intent behind `handle`, removing it — or `null` (unknown, used, expired). */
@@ -50,7 +55,11 @@ class ExternalLinkIntents {
         this.intents.delete(handle);
         if (stored.expiresAt < this.now())
             return null;
-        return { userId: stored.userId, provider: stored.provider };
+        return {
+            userId: stored.userId,
+            provider: stored.provider,
+            ...(stored.returnTo !== undefined ? { returnTo: stored.returnTo } : {}),
+        };
     }
     prune() {
         const now = this.now();

package/dist/auth/hub-sessions.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userManagementInternal = userManagementInternal;
+exports.createSessionBacking = createSessionBacking;
+exports.sessionBackingFrom = sessionBackingFrom;
+exports.createSessionTokenCheck = createSessionTokenCheck;
+/**
+ * The hub's two uses of the login-session table, which `local-auth` owns and
+ * reaches only through its hub-internal surface (`UserManagementInternal`):
+ *
+ *  - {@link createSessionBacking} — what THE session mint opens, continues and
+ *    rotates sessions through (`session-mint.ts`);
+ *  - {@link createSessionTokenCheck} — the question `AuthService.verifyToken`
+ *    asks of every session-grade token: does its session still exist?
+ *
+ * Both resolve `user-management` per call: a hub whose local-auth is not up
+ * mints nothing and accepts no session (fail closed).
+ */
+const system_1 = require("@camstack/system");
+/** The hub-internal user-management surface right now, or `null`. */
+function userManagementInternal(registry) {
+    return (0, system_1.getUserManagementInternal)(registry.getSingleton('user-management'));
+}
+function createSessionBacking(sessions, lifetimes) {
+    return {
+        open: async (input) => {
+            const { session, refreshToken } = await sessions.create({
+                ...input,
+                lifetimeMs: lifetimes().sessionMs,
+            });
+            return { session, refreshToken };
+        },
+        extend: async (sessionId) => sessions.extend(sessionId, lifetimes().sessionMs),
+        rotate: async (refreshToken) => {
+            const result = await sessions.refresh(refreshToken, lifetimes().sessionMs);
+            return result.ok
+                ? { ok: true, session: result.session, refreshToken: result.refreshToken }
+                : { ok: false, reason: result.reason };
+        },
+        accessSec: () => lifetimes().accessSec,
+    };
+}
+/** The session backing behind `registry`'s user-management, or `null` while it is not up. */
+function sessionBackingFrom(registry, lifetimes) {
+    return () => {
+        const internal = userManagementInternal(registry);
+        return internal === null ? null : createSessionBacking(internal.sessions, lifetimes);
+    };
+}
+/**
+ * Is the session behind this (already signature-verified, session-grade)
+ * token still live? A token with a `sid` must name an active session of the
+ * same user. A token WITHOUT one predates sessions: it is accepted for one
+ * release unless it was issued before the user's cutoff (logout everywhere,
+ * a password change, deletion).
+ */
+function createSessionTokenCheck(registry) {
+    return (payload) => {
+        const internal = userManagementInternal(registry);
+        if (internal === null)
+            return 'session-store-unavailable';
+        const userId = payload.userId;
+        if (payload.sid !== undefined) {
+            const check = internal.sessions.check(payload.sid);
+            if (check.state !== 'active')
+                return `session-${check.state}`;
+            return check.session.userId === userId ? null : 'session-user-mismatch';
+        }
+        if (userId === undefined)
+            return 'session-unknown';
+        const issuedAtMs = (payload.iat ?? 0) * 1000;
+        return issuedAtMs < internal.sessions.legacyCutoff(userId) ? 'issued-before-revocation' : null;
+    };
+}

package/dist/auth/native-link-completions.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeLinkCompletions = exports.NATIVE_LINK_CODE_TTL_MS = exports.NATIVE_LINK_CODE_PREFIX = void 0;
+/**
+ * Native-app account links waiting for the app to claim them (D801).
+ *
+ * A link started from the native viewer finishes in the SYSTEM browser, which
+ * holds no hub session — so the SSO finish cannot check "the browser is signed
+ * in as the intent's user" (D782's binding). Instead it parks what it verified
+ * — the intent's user and the IdP identity — under a one-time code, and sends
+ * the browser back to the app's custom scheme with that code. The app claims it
+ * over `auth.completeExternalLink` with its own bearer, and the router binds it
+ * there: the caller must BE the intent's user.
+ *
+ * Same shape as the handoff codes: the raw code exists once (only its hash is
+ * kept), lives 60 s, is consumed by its first claim attempt whatever the
+ * outcome, and the store is bounded. In memory: a hub restart mid-link costs
+ * one more tap.
+ */
+const node_crypto_1 = require("node:crypto");
+exports.NATIVE_LINK_CODE_PREFIX = 'nlc_';
+exports.NATIVE_LINK_CODE_TTL_MS = 60_000;
+const MAX_PENDING = 1_000;
+function hash(code) {
+    return (0, node_crypto_1.createHash)('sha256').update(code).digest('hex');
+}
+class NativeLinkCompletions {
+    pending = new Map();
+    now;
+    ttlMs;
+    constructor(opts = {}) {
+        this.now = opts.now ?? Date.now;
+        this.ttlMs = opts.ttlMs ?? exports.NATIVE_LINK_CODE_TTL_MS;
+    }
+    /** Park a verified link; returns the raw one-time code. */
+    park(link) {
+        this.prune();
+        while (this.pending.size >= MAX_PENDING) {
+            const oldest = this.pending.keys().next();
+            if (oldest.done)
+                break;
+            this.pending.delete(oldest.value);
+        }
+        const code = `${exports.NATIVE_LINK_CODE_PREFIX}${(0, node_crypto_1.randomBytes)(32).toString('base64url')}`;
+        this.pending.set(hash(code), { ...link, expiresAt: this.now() + this.ttlMs });
+        return code;
+    }
+    /** The parked link, consumed — or `null` (unknown, used, expired). */
+    claim(code) {
+        const key = hash(code);
+        const entry = this.pending.get(key);
+        if (entry === undefined)
+            return null;
+        this.pending.delete(key);
+        if (entry.expiresAt <= this.now())
+            return null;
+        const { expiresAt: _expiresAt, ...link } = entry;
+        return link;
+    }
+    prune() {
+        const now = this.now();
+        for (const [key, entry] of this.pending) {
+            if (entry.expiresAt <= now)
+                this.pending.delete(key);
+        }
+    }
+}
+exports.NativeLinkCompletions = NativeLinkCompletions;