@hotmeshio/long-tail 0.28.4 → 0.30.0

package/build/api/roles.js

@@ -50,6 +50,7 @@ exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
 const types_1 = require("../services/role/types");
 const badge_grant_1 = require("../services/role/badge-grant");
+const scan_done_1 = require("../services/role/scan-done");
 const facet_sql_1 = require("../services/escalation/facet-sql");
 const list_schema_1 = require("../shared/list-schema");
 /**
@@ -296,6 +297,9 @@ async function updateRole(input) {
         const grantError = (0, badge_grant_1.badgeGrantError)(input.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
         if (grantError)
             return { status: 400, error: grantError };
+        const scanDoneProblem = (0, scan_done_1.scanDoneError)(input.properties?.[types_1.ROLE_PROPERTY_KEYS.SCAN_DONE]);
+        if (scanDoneProblem)
+            return { status: 400, error: scanDoneProblem };
         const listSchemaError = input.list_schema != null ? (0, list_schema_1.listSchemaRelationsError)(input.list_schema) : null;
         if (listSchemaError)
             return { status: 400, error: `list_schema: ${listSchemaError}` };

package/build/api/scan-codes/choice.js

@@ -41,6 +41,7 @@ const identity_1 = require("./identity");
 const grant_1 = require("./grant");
 const helpers_1 = require("../escalations/helpers");
 const context_1 = require("./context");
+const present_1 = require("./present");
 const choice_roles_1 = require("./choice-roles");
 const x_lt_actions_1 = require("../../shared/form-validation/x-lt-actions");
 const locate_1 = require("./locate");
@@ -134,12 +135,14 @@ async function executeScanChoice(input, auth) {
         // same double-actor race a second scan loses.
         const located = await (0, locate_1.locateForStep)(step, ctx, 2);
         const presented = located?.escalations.find((e) => e.id === input.escalationId);
-        if (!presented) {
+        if (!presented || !(0, present_1.choiceOffered)(choice, presented)) {
             return decorate((0, context_1.conflict)('the item is no longer in the presented state'), ctx, input);
         }
-        // 7. Dispatch through the same atomic executors a direct scan uses.
+        // 7. Dispatch through the same atomic executors a direct scan uses; the
+        // choice's done copy reads the row it acted on.
         const synthesized = { query: step.query, verb: choice.verb, params: choice.params };
-        const result = decorate(await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, presented), ctx, input);
+        const tpl = { ...(0, context_1.templateContext)(ctx), item: presented.metadata ?? {} };
+        const result = decorate((0, context_1.withDone)(await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, presented), choice, tpl), ctx, input);
         // 8. Settle the badge: refund a spend whose act did not land
         const acting = await (0, grant_1.settleGrant)(ctx, result);
         if (acting && result.data)

package/build/api/scan-codes/context.d.ts

@@ -78,4 +78,10 @@ export declare function templated<T>(step: ScanStep, ctx: StepContext, render: (
  * bags the copy may read (the container a subject step located, a fill's
  * batch); an unreadable token renders empty rather than failing the act.
  */
-export declare function withDone(result: LTApiResult<ScanExecuteResponse>, step: ScanStep, tpl: scanCodeService.ScanTemplateContext): LTApiResult<ScanExecuteResponse>;
+export declare function withDone(result: LTApiResult<ScanExecuteResponse>, step: Pick<ScanStep, 'done'>, tpl: scanCodeService.ScanTemplateContext): LTApiResult<ScanExecuteResponse>;
+/**
+ * Attach the step's `follow` to a write that completed the held subject: the
+ * code the station replays and the target it waits for, so the subject's
+ * next row is held without scanning it again.
+ */
+export declare function withFollow(result: LTApiResult<ScanExecuteResponse>, step: Pick<ScanStep, 'follow'>, ctx: StepContext): LTApiResult<ScanExecuteResponse>;

package/build/api/scan-codes/context.js

@@ -47,6 +47,7 @@ exports.notPrimed = notPrimed;
 exports.refused = refused;
 exports.templated = templated;
 exports.withDone = withDone;
+exports.withFollow = withFollow;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const escalationService = __importStar(require("../../services/escalation"));
 const types_1 = require("../../types");
@@ -160,3 +161,26 @@ function withDone(result, step, tpl) {
         return result;
     return { ...result, data: { ...data, done: { markdown: scanCodeService.renderScanCopy(step.done.markdown, tpl) } } };
 }
+/**
+ * Attach the step's `follow` to a write that completed the held subject: the
+ * code the station replays and the target it waits for, so the subject's
+ * next row is held without scanning it again.
+ */
+function withFollow(result, step, ctx) {
+    const data = result.data;
+    const subject = ctx.subject;
+    if (!step.follow || !subject || !data || data.outcome !== types_1.SCAN_OUTCOMES.EXECUTED || !data.clearSubject)
+        return result;
+    return {
+        ...result,
+        data: {
+            ...data,
+            follow: {
+                code: subject.code,
+                roles: step.follow.roles,
+                waitSeconds: step.follow.waitSeconds ?? types_1.SCAN_FOLLOW_WAIT_DEFAULT_SECONDS,
+                target: { facet: subject.scheme.target_facet, value: subject.parsed.target },
+            },
+        },
+    };
+}

package/build/api/scan-codes/execute.js

@@ -114,8 +114,10 @@ async function executeScanCode(input, auth) {
         let result = null;
         for (let i = 0; i < rule.steps.length && !result; i++) {
             const stepResult = await executeStep(rule.steps[i], ctx);
-            if (stepResult)
-                result = decorate((0, context_1.withDone)(stepResult, rule.steps[i], (0, context_1.templateContext)(ctx)), ctx, i);
+            if (stepResult) {
+                const step = rule.steps[i];
+                result = decorate((0, context_1.withFollow)((0, context_1.withDone)(stepResult, step, (0, context_1.templateContext)(ctx)), step, ctx), ctx, i);
+            }
         }
         // 4. Nothing matched: a stale subject, or the fallback screen
         if (!result) {

package/build/api/scan-codes/present.d.ts

@@ -1,6 +1,8 @@
-import { type ScanExecuteResponse, type ScanStep } from '../../types';
+import { type LTEscalationRecord, type ScanChoice, type ScanExecuteResponse, type ScanStep } from '../../types';
 import type { LTApiResult } from '../../types/sdk';
 import { type StepContext } from './context';
+/** True when the row carries every facet value the choice is offered under. */
+export declare function choiceOffered(choice: Pick<ScanChoice, 'when'>, row: LTEscalationRecord): boolean;
 /**
  * Locate the target and present the step's choices. Choices whose identity
  * requirement is unsatisfied come back withheld — the screen renders the

package/build/api/scan-codes/present.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.choiceOffered = choiceOffered;
 exports.presentStep = presentStep;
 const scanCodeService = __importStar(require("../../services/scan-code"));
 const types_1 = require("../../types");
@@ -41,6 +42,11 @@ const choice_roles_1 = require("./choice-roles");
 const locate_1 = require("./locate");
 const verbs_1 = require("./verbs");
 const context_1 = require("./context");
+/** True when the row carries every facet value the choice is offered under. */
+function choiceOffered(choice, row) {
+    const meta = (row.metadata ?? {});
+    return Object.entries(choice.when ?? {}).every(([key, value]) => meta[key] === value);
+}
 /** The step's facts rendered against the presented row; unreadable tokens render empty. */
 function renderFacts(step, ctx, row) {
     if (!step.facts)
@@ -83,19 +89,26 @@ async function presentStep(step, ctx) {
     const roleHeld = await Promise.all((step.choices ?? []).map((choice) => (0, choice_roles_1.holdsChoiceRole)(choice, ctx.auth.userId)));
     const only = step.choices?.length === 1 ? step.choices[0] : undefined;
     const autoSelect = step.autoSelectSingle === true && only !== undefined && !only.confirm;
-    if (autoSelect && (!only.requireActingIdentity || satisfied) && roleHeld[0]) {
-        return (0, verbs_1.dispatchChoiceVerb)({ query: step.query, verb: only.verb, params: only.params }, ctx, escalation);
+    if (autoSelect && (!only.requireActingIdentity || satisfied) && roleHeld[0] && choiceOffered(only, escalation)) {
+        const tpl = { ...(0, context_1.templateContext)(ctx), item: escalation.metadata ?? {} };
+        return (0, context_1.withDone)(await (0, verbs_1.dispatchChoiceVerb)({ query: step.query, verb: only.verb, params: only.params }, ctx, escalation), only, tpl);
     }
-    const choices = (step.choices ?? []).map((choice, index) => ({
-        index,
-        label: choice.label,
-        verb: choice.verb,
-        ...(choice.confirm ? { confirm: choice.confirm } : {}),
-        ...(choice.requireActingIdentity ? { requireActingIdentity: true } : {}),
-        ...(choice.roles?.length ? { roles: choice.roles } : {}),
-        ...(choice.code ? { code: choice.code } : {}),
-        withheld: (!!choice.requireActingIdentity && !satisfied) || !roleHeld[index],
-    }));
+    // A choice the row's state does not offer, or one hidden from a person
+    // without its roles, is left off the screen; the index stays the config's.
+    const choices = (step.choices ?? []).flatMap((choice, index) => {
+        if (!choiceOffered(choice, escalation) || (choice.hidden && !roleHeld[index]))
+            return [];
+        return [{
+                index,
+                label: choice.label,
+                verb: choice.verb,
+                ...(choice.confirm ? { confirm: choice.confirm } : {}),
+                ...(choice.requireActingIdentity ? { requireActingIdentity: true } : {}),
+                ...(choice.roles?.length ? { roles: choice.roles } : {}),
+                ...(choice.code ? { code: choice.code } : {}),
+                withheld: (!!choice.requireActingIdentity && !satisfied) || !roleHeld[index],
+            }];
+    });
     return {
         status: 200,
         data: {

package/build/routes/oauth.d.ts

@@ -3,5 +3,6 @@ export declare function setOAuthConfig(cfg: {
     autoProvision?: boolean;
     defaultRoleType?: 'admin' | 'member';
     baseUrl?: string;
+    allowedDomains?: string[];
 }): void;
 export default router;

package/build/routes/oauth.js

@@ -5,13 +5,17 @@ const http_1 = require("../lib/http");
 const auth_1 = require("../modules/auth");
 const logger_1 = require("../lib/logger");
 const oauth_1 = require("../services/oauth");
+const provisioning_1 = require("../services/oauth/provisioning");
 const user_1 = require("../services/user");
 const router = (0, http_1.Router)();
+// What a refused person reads. The reason is logged, never shown.
+const SIGN_IN_REFUSED = 'This account is not allowed to sign in here. Contact an administrator.';
 // ── OAuth startup config (set by initializeOAuth) ────────────────────────────
 let _oauthConfig = {
     autoProvision: true,
     defaultRoleType: 'member',
     baseUrl: '',
+    allowedDomains: [],
 };
 function setOAuthConfig(cfg) {
     if (cfg.autoProvision !== undefined)
@@ -20,6 +24,8 @@ function setOAuthConfig(cfg) {
         _oauthConfig.defaultRoleType = cfg.defaultRoleType;
     if (cfg.baseUrl)
         _oauthConfig.baseUrl = cfg.baseUrl;
+    if (cfg.allowedDomains)
+        _oauthConfig.allowedDomains = (0, provisioning_1.normalizeDomains)(cfg.allowedDomains);
 }
 /**
  * GET /api/auth/oauth/providers
@@ -115,12 +121,20 @@ router.get('/:provider/callback', async (req, res) => {
         // Find or create the user
         let user = await (0, oauth_1.getUserByOAuthProvider)(provider, userInfo.providerUserId);
         if (!user && userInfo.email) {
-            // Try matching by email
+            // A provider id meets an invited account once, by its verified email
             user = await (0, user_1.getUserByEmail)(userInfo.email);
+            if (user)
+                logger_1.loggerRegistry.info(`[oauth] bound ${provider} id to existing account ${user.id} by verified email`);
         }
         if (!user) {
             if (!_oauthConfig.autoProvision) {
-                res.status(403).json({ error: 'No account found. Contact an administrator.' });
+                logger_1.loggerRegistry.warn(`[oauth] refused ${provider} sign-in: no account and auto-provision is off`);
+                res.redirect(`/login?error=${encodeURIComponent(SIGN_IN_REFUSED)}`);
+                return;
+            }
+            if (!(0, provisioning_1.mayProvision)(userInfo.email, _oauthConfig.allowedDomains)) {
+                logger_1.loggerRegistry.warn(`[oauth] refused ${provider} sign-in: email domain not in allowedDomains`);
+                res.redirect(`/login?error=${encodeURIComponent(SIGN_IN_REFUSED)}`);
                 return;
             }
             // Auto-provision new user

package/build/services/oauth/index.d.ts

@@ -2,6 +2,7 @@ import type { LTOAuthStartConfig } from '../../types/oauth';
 export { encrypt, decrypt, getEncryptionKey, setEncryptionKey } from './crypto';
 export { createOAuthState, consumeOAuthState } from './state';
 export { registerProvider, getProvider, listProviders } from './providers';
+export { normalizeDomains, emailDomain, mayProvision } from './provisioning';
 export type { ProviderHandler, OAuthTokens } from './providers';
 export { upsertOAuthToken, getOAuthToken, getFreshAccessToken, listOAuthConnections, deleteOAuthConnection, getUserByOAuthProvider, } from './db';
 /**

package/build/services/oauth/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getUserByOAuthProvider = exports.deleteOAuthConnection = exports.listOAuthConnections = exports.getFreshAccessToken = exports.getOAuthToken = exports.upsertOAuthToken = exports.listProviders = exports.getProvider = exports.registerProvider = exports.consumeOAuthState = exports.createOAuthState = exports.setEncryptionKey = exports.getEncryptionKey = exports.decrypt = exports.encrypt = void 0;
+exports.getUserByOAuthProvider = exports.deleteOAuthConnection = exports.listOAuthConnections = exports.getFreshAccessToken = exports.getOAuthToken = exports.upsertOAuthToken = exports.mayProvision = exports.emailDomain = exports.normalizeDomains = exports.listProviders = exports.getProvider = exports.registerProvider = exports.consumeOAuthState = exports.createOAuthState = exports.setEncryptionKey = exports.getEncryptionKey = exports.decrypt = exports.encrypt = void 0;
 exports.initializeOAuth = initializeOAuth;
 const crypto_1 = require("./crypto");
 const providers_1 = require("./providers");
@@ -17,6 +17,10 @@ var providers_2 = require("./providers");
 Object.defineProperty(exports, "registerProvider", { enumerable: true, get: function () { return providers_2.registerProvider; } });
 Object.defineProperty(exports, "getProvider", { enumerable: true, get: function () { return providers_2.getProvider; } });
 Object.defineProperty(exports, "listProviders", { enumerable: true, get: function () { return providers_2.listProviders; } });
+var provisioning_1 = require("./provisioning");
+Object.defineProperty(exports, "normalizeDomains", { enumerable: true, get: function () { return provisioning_1.normalizeDomains; } });
+Object.defineProperty(exports, "emailDomain", { enumerable: true, get: function () { return provisioning_1.emailDomain; } });
+Object.defineProperty(exports, "mayProvision", { enumerable: true, get: function () { return provisioning_1.mayProvision; } });
 var db_1 = require("./db");
 Object.defineProperty(exports, "upsertOAuthToken", { enumerable: true, get: function () { return db_1.upsertOAuthToken; } });
 Object.defineProperty(exports, "getOAuthToken", { enumerable: true, get: function () { return db_1.getOAuthToken; } });

package/build/services/oauth/providers/github.js

@@ -74,7 +74,8 @@ function createGitHubHandler(cfg) {
             ]);
             const user = await userRes.json();
             const emails = await emailRes.json().catch(() => []);
-            const primary = emails.find((e) => e.primary)?.email || emails[0]?.email || null;
+            const verified = emails.filter((e) => e.verified === true);
+            const primary = verified.find((e) => e.primary)?.email || verified[0]?.email || null;
             return {
                 provider: 'github',
                 providerUserId: String(user.id),

package/build/services/oauth/providers/google.js

@@ -75,14 +75,14 @@ function createGoogleHandler(cfg) {
             };
         },
         async fetchUserInfo(accessToken) {
-            const res = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+            const res = await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
                 headers: { Authorization: `Bearer ${accessToken}` },
             });
             const data = await res.json();
             return {
                 provider: 'google',
-                providerUserId: data.id,
-                email: data.email || null,
+                providerUserId: data.sub || data.id,
+                email: data.email_verified === true && data.email ? data.email : null,
                 displayName: data.name || null,
                 raw: data,
             };

package/build/services/oauth/providers/microsoft.js

@@ -34,9 +34,12 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMicrosoftHandler = createMicrosoftHandler;
+const MULTI_TENANT_AUTHORITIES = new Set(['common', 'organizations', 'consumers']);
 function createMicrosoftHandler(cfg) {
     const redirectUri = cfg.redirectUri || '';
     const tenantId = process.env.OAUTH_MICROSOFT_TENANT_ID || 'common';
+    // Graph does not verify mail or the UPN. Only a single-tenant authority vouches for the account.
+    const singleTenant = !MULTI_TENANT_AUTHORITIES.has(tenantId);
     let _ms;
     async function getClient() {
         if (!_ms) {
@@ -79,7 +82,7 @@ function createMicrosoftHandler(cfg) {
             return {
                 provider: 'microsoft',
                 providerUserId: data.id,
-                email: data.mail || data.userPrincipalName || null,
+                email: singleTenant ? data.mail || data.userPrincipalName || null : null,
                 displayName: data.displayName || null,
                 raw: data,
             };

package/build/services/oauth/providers/mock.js

@@ -66,7 +66,7 @@ function createMockHandler(cfg) {
             return {
                 provider: 'mock',
                 providerUserId: data.sub || data.id || 'mock-user',
-                email: data.email || null,
+                email: data.email_verified === true && data.email ? data.email : null,
                 displayName: data.name || null,
                 raw: data,
             };

package/build/services/oauth/provisioning.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Decides whether an OAuth sign-in may create its own account.
+ * Enforced server side in the callback; provider hints are not trusted.
+ */
+export declare function normalizeDomains(domains: string[] | undefined): string[];
+export declare function emailDomain(email: string | null | undefined): string | undefined;
+/** Whether a sign-in with this email may create its own account. Empty list: any. */
+export declare function mayProvision(email: string | null | undefined, allowedDomains: string[]): boolean;

package/build/services/oauth/provisioning.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Decides whether an OAuth sign-in may create its own account.
+ * Enforced server side in the callback; provider hints are not trusted.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDomains = normalizeDomains;
+exports.emailDomain = emailDomain;
+exports.mayProvision = mayProvision;
+function normalizeDomains(domains) {
+    return (domains ?? []).map((d) => d.trim().toLowerCase().replace(/^@/, '')).filter(Boolean);
+}
+function emailDomain(email) {
+    const at = email?.lastIndexOf('@') ?? -1;
+    return at > 0 ? email.slice(at + 1).toLowerCase() : undefined;
+}
+/** Whether a sign-in with this email may create its own account. Empty list: any. */
+function mayProvision(email, allowedDomains) {
+    if (allowedDomains.length === 0)
+        return true;
+    const domain = emailDomain(email);
+    return domain !== undefined && allowedDomains.includes(domain);
+}

package/build/services/role/scan-done.d.ts

@@ -0,0 +1,7 @@
+import { type RoleScanDone } from './types';
+export declare const SCAN_DONE_RETURN_HOME = "home";
+export declare const SCAN_DONE_AFTER_SECONDS_DEFAULT = 2;
+/** The problem with a `properties.scan_done` value, or null when it is usable (or absent). */
+export declare function scanDoneError(value: unknown): string | null;
+/** The role's return policy from its properties bag, or null when it declares none (or an unusable one). */
+export declare function readScanDone(properties: Record<string, unknown> | null | undefined): RoleScanDone | null;

package/build/services/role/scan-done.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCAN_DONE_AFTER_SECONDS_DEFAULT = exports.SCAN_DONE_RETURN_HOME = void 0;
+exports.scanDoneError = scanDoneError;
+exports.readScanDone = readScanDone;
+const types_1 = require("./types");
+exports.SCAN_DONE_RETURN_HOME = 'home';
+exports.SCAN_DONE_AFTER_SECONDS_DEFAULT = 2;
+const AFTER_SECONDS_MAX = 60;
+/** The problem with a `properties.scan_done` value, or null when it is usable (or absent). */
+function scanDoneError(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return 'properties.scan_done must be an object';
+    const done = value;
+    const known = new Set(['return', 'after_seconds']);
+    const extra = Object.keys(done).filter((k) => !known.has(k));
+    if (extra.length)
+        return `properties.scan_done has unknown key(s): ${extra.join(', ')}`;
+    if (typeof done.return !== 'string' || !(done.return === exports.SCAN_DONE_RETURN_HOME || done.return.startsWith('/'))) {
+        return `properties.scan_done.return must be '${exports.SCAN_DONE_RETURN_HOME}' or a dashboard-relative route`;
+    }
+    if (done.after_seconds !== undefined
+        && (!Number.isInteger(done.after_seconds) || done.after_seconds < 0 || done.after_seconds > AFTER_SECONDS_MAX)) {
+        return `properties.scan_done.after_seconds must be an integer from 0 to ${AFTER_SECONDS_MAX}`;
+    }
+    return null;
+}
+/** The role's return policy from its properties bag, or null when it declares none (or an unusable one). */
+function readScanDone(properties) {
+    const value = properties?.[types_1.ROLE_PROPERTY_KEYS.SCAN_DONE];
+    if (value === undefined || value === null || scanDoneError(value))
+        return null;
+    return value;
+}

package/build/services/role/seed.js

@@ -9,6 +9,7 @@ const logger_1 = require("../../lib/logger");
 const index_1 = require("./index");
 const sql_1 = require("./sql");
 const badge_grant_1 = require("./badge-grant");
+const scan_done_1 = require("./scan-done");
 const list_schema_1 = require("../../shared/list-schema");
 const types_1 = require("./types");
 /** Recorded on schema snapshots written by the startup apply. */
@@ -85,6 +86,9 @@ async function applyRoleConfig(cfg, codeOwned) {
     const grantError = (0, badge_grant_1.badgeGrantError)(cfg.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
     if (grantError)
         throw new Error(`role ${cfg.role}: ${grantError}`);
+    const scanDoneProblem = (0, scan_done_1.scanDoneError)(cfg.properties?.[types_1.ROLE_PROPERTY_KEYS.SCAN_DONE]);
+    if (scanDoneProblem)
+        throw new Error(`role ${cfg.role}: ${scanDoneProblem}`);
     const listSchemaError = cfg.list_schema != null ? (0, list_schema_1.listSchemaRelationsError)(cfg.list_schema) : null;
     if (listSchemaError)
         throw new Error(`role ${cfg.role}: list_schema: ${listSchemaError}`);

package/build/services/role/types.d.ts

@@ -19,6 +19,9 @@ export interface EscalationChain {
  *    A badge scanned on a device signed in as a member of this role mints
  *    its acting grant under this policy instead of the badge scheme's own
  *    (see api/scan-codes/badge-policy.ts).
+ *  - SCAN_DONE: RoleScanDone — where a station locked to this role goes once
+ *    a scan act completes its row: the kiosk home or a route, after a pause
+ *    on the done copy.
  *  - LINK_VARIABLES: RoleLinkVariable[] — metadata facet names members bind
  *    per device. Pins may reference `{lt:name}` as a whole facet value
  *    (e.g. `facets={"region":"{lt:region}"}`); the dashboard substitutes
@@ -32,7 +35,15 @@ export declare const ROLE_PROPERTY_KEYS: {
     readonly KIOSK: "kiosk";
     readonly LINK_VARIABLES: "link_variables";
     readonly BADGE_GRANT: "badge_grant";
+    readonly SCAN_DONE: "scan_done";
 };
+/** Where a station returns after a scan act completes its row. */
+export interface RoleScanDone {
+    /** 'home' is the kiosk home (portal or list); otherwise a dashboard-relative route. */
+    return: 'home' | string;
+    /** Seconds the done copy stays up first (0-60, default 2). */
+    after_seconds?: number;
+}
 /** A station role's badge policy. Absent fields keep the badge scheme's value. */
 export interface RoleBadgeGrant {
     /** How long a badge scan stays primed (1-86400 s). */

package/build/services/role/types.js

@@ -18,6 +18,9 @@ exports.PORTAL_KEY = exports.PORTAL_LIMITS = exports.ROLE_PROPERTY_KEYS = void 0
  *    A badge scanned on a device signed in as a member of this role mints
  *    its acting grant under this policy instead of the badge scheme's own
  *    (see api/scan-codes/badge-policy.ts).
+ *  - SCAN_DONE: RoleScanDone — where a station locked to this role goes once
+ *    a scan act completes its row: the kiosk home or a route, after a pause
+ *    on the done copy.
  *  - LINK_VARIABLES: RoleLinkVariable[] — metadata facet names members bind
  *    per device. Pins may reference `{lt:name}` as a whole facet value
  *    (e.g. `facets={"region":"{lt:region}"}`); the dashboard substitutes
@@ -31,6 +34,7 @@ exports.ROLE_PROPERTY_KEYS = {
     KIOSK: 'kiosk',
     LINK_VARIABLES: 'link_variables',
     BADGE_GRANT: 'badge_grant',
+    SCAN_DONE: 'scan_done',
 };
 /** Bounds for a role's portals: how many, and the matrix of each (rows of cells, each cell a pin). */
 exports.PORTAL_LIMITS = {

package/build/services/scan-code/validate.js

@@ -151,8 +151,57 @@ function assertValidChoices(choices, at) {
                 throw new Error(`${cat}: duplicate code "${choice.code}"`);
             codes.add(choice.code);
         }
+        if (choice.done !== undefined) {
+            if (!choice.done || typeof choice.done !== 'object' || typeof choice.done.markdown !== 'string' || !choice.done.markdown) {
+                throw new Error(`${cat}: done.markdown is required`);
+            }
+            if (!types_1.SCAN_MUTATING_VERBS.includes(choice.verb)) {
+                throw new Error(`${cat}: done applies only to choices that write`);
+            }
+        }
+        if (choice.hidden !== undefined) {
+            if (typeof choice.hidden !== 'boolean')
+                throw new Error(`${cat}: hidden must be a boolean`);
+            if (choice.hidden && !choice.roles?.length)
+                throw new Error(`${cat}: hidden requires roles`);
+        }
+        if (choice.when !== undefined)
+            assertValidWhen(choice.when, cat);
     });
 }
+/** A choice's `when`: facet keys to scalar values the row must carry. */
+function assertValidWhen(when, at) {
+    if (!when || typeof when !== 'object' || Array.isArray(when) || Object.keys(when).length === 0) {
+        throw new Error(`${at}: when must be a non-empty object of facet values`);
+    }
+    for (const [key, value] of Object.entries(when)) {
+        if (!facet_sql_1.FACET_KEY.test(key))
+            throw new Error(`${at}: when key "${key}" is not a facet key`);
+        if (!['string', 'number', 'boolean'].includes(typeof value)) {
+            throw new Error(`${at}: when.${key} must be a string, number, or boolean`);
+        }
+    }
+}
+/** A step's `follow`: the roles the subject's next row may be in, and how long to wait for it. */
+function assertValidFollow(step, at) {
+    const follow = step.follow;
+    if (follow === undefined)
+        return;
+    if (!follow || typeof follow !== 'object' || Array.isArray(follow))
+        throw new Error(`${at}: follow must be an object`);
+    if (!Array.isArray(follow.roles) || follow.roles.length === 0
+        || follow.roles.some((r) => typeof r !== 'string' || !r)) {
+        throw new Error(`${at}: follow.roles must be a non-empty array of role names`);
+    }
+    if (follow.waitSeconds !== undefined
+        && (!Number.isInteger(follow.waitSeconds) || follow.waitSeconds < 1 || follow.waitSeconds > types_1.SCAN_FOLLOW_WAIT_MAX_SECONDS)) {
+        throw new Error(`${at}: follow.waitSeconds must be an integer from 1 to ${types_1.SCAN_FOLLOW_WAIT_MAX_SECONDS}`);
+    }
+    if (!types_1.SCAN_MUTATING_VERBS.includes(step.verb))
+        throw new Error(`${at}: follow applies only to steps that write`);
+    if (!step.subject)
+        throw new Error(`${at}: follow applies only to steps that act on the held subject`);
+}
 /**
  * Reject incoherent rule steps at write time: a rule that can never
  * execute its verb must fail the upsert, not the factory-floor scan.
@@ -247,6 +296,7 @@ function assertValidSteps(steps) {
                 throw new Error(`${at}: done applies only to steps that write`);
             }
         }
+        assertValidFollow(step, at);
         assertValidTemplateTokens(step, at);
         if (step.query && step.query.roles && !Array.isArray(step.query.roles)) {
             throw new Error(`${at}: query.roles must be an array`);

package/build/start/config.js

@@ -98,6 +98,7 @@ async function applyServerAuthConfig(startConfig) {
             autoProvision: startConfig.auth.oauth.autoProvision,
             defaultRoleType: startConfig.auth.oauth.defaultRoleType,
             baseUrl: startConfig.auth.oauth.baseUrl,
+            allowedDomains: startConfig.auth.oauth.allowedDomains,
         });
     }
     const oauthServer = startConfig.auth?.oauthServer