@hotmeshio/long-tail 0.22.1 → 0.22.2

package/build/index.d.ts

@@ -12,6 +12,7 @@ export * as TaskService from './services/task';
 export * as EscalationService from './services/escalation';
 export * as ConfigService from './services/config';
 export * as UserService from './services/user';
+export { assertValidScheme as assertValidScanScheme, assertValidSteps as assertValidScanSteps, assertValidIdentityRule as assertValidScanIdentityRule, isValidGtin, normalizeGtin, type ScanSchemeInput, type ScanRuleInput, } from './services/scan-code';
 export * as TopicService from './services/topics';
 export { seedSystemTopics, seedConfigTopics } from './services/topics/system-topics';
 export { ltConfig } from './modules/ltconfig';

package/build/index.js

@@ -36,8 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = void 0;
+exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
+exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
@@ -70,6 +70,12 @@ exports.TaskService = __importStar(require("./services/task"));
 exports.EscalationService = __importStar(require("./services/escalation"));
 exports.ConfigService = __importStar(require("./services/config"));
 exports.UserService = __importStar(require("./services/user"));
+var scan_code_1 = require("./services/scan-code");
+Object.defineProperty(exports, "assertValidScanScheme", { enumerable: true, get: function () { return scan_code_1.assertValidScheme; } });
+Object.defineProperty(exports, "assertValidScanSteps", { enumerable: true, get: function () { return scan_code_1.assertValidSteps; } });
+Object.defineProperty(exports, "assertValidScanIdentityRule", { enumerable: true, get: function () { return scan_code_1.assertValidIdentityRule; } });
+Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return scan_code_1.isValidGtin; } });
+Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return scan_code_1.normalizeGtin; } });
 exports.TopicService = __importStar(require("./services/topics"));
 var system_topics_1 = require("./services/topics/system-topics");
 Object.defineProperty(exports, "seedSystemTopics", { enumerable: true, get: function () { return system_topics_1.seedSystemTopics; } });

package/build/lib/db/schemas/037_scan_gtin_and_subject_grants.sql

@@ -0,0 +1,27 @@
+-- Migration 037: GTIN scan schemes and subject-bound acting grants
+--
+-- encoding 'gtin': a scheme whose codes are manufacturer barcodes (UPC-A,
+-- EAN-13, EAN-8, GTIN-14). The code carries no scheme or category; the
+-- check digit identifies it, and the scheme's single rule is category '0'.
+--
+-- grant_scope (identity kind only):
+--   'action'  each mutating act spends one use of the grant.
+--   'subject' the first act binds the grant to the held subject (the item
+--             the station is holding); further acts on that same subject do
+--             not count, and the grant cannot act on any other subject.
+--
+-- lt_ephemeral_credentials.bind_on_use / bound_ref carry that binding.
+
+ALTER TABLE lt_config_scan_schemes
+  DROP CONSTRAINT IF EXISTS lt_config_scan_schemes_encoding_check;
+ALTER TABLE lt_config_scan_schemes
+  ADD CONSTRAINT lt_config_scan_schemes_encoding_check
+    CHECK (encoding IN ('fixed', 'delimited', 'gtin'));
+
+ALTER TABLE lt_config_scan_schemes
+  ADD COLUMN IF NOT EXISTS grant_scope TEXT NOT NULL DEFAULT 'action'
+    CHECK (grant_scope IN ('action', 'subject'));
+
+ALTER TABLE lt_ephemeral_credentials
+  ADD COLUMN IF NOT EXISTS bind_on_use BOOLEAN NOT NULL DEFAULT FALSE,
+  ADD COLUMN IF NOT EXISTS bound_ref TEXT;

package/build/routes/escalations/acting.d.ts

@@ -2,6 +2,11 @@ import type { Request, Response } from 'express';
 import type { LTApiAuth } from '../../types/sdk';
 /** The header a shared station device rides its badge grant on. */
 export declare const ACTING_TOKEN_HEADER = "x-lt-acting-token";
+/**
+ * Uses the grant has left after this request spent one: a count, or
+ * `unbounded` while only the TTL limits it. The client retires its grant on 0.
+ */
+export declare const ACTING_REMAINING_HEADER = "x-lt-acting-remaining";
 /**
  * The effective actor for an escalation WORK verb (claim, release, resolve):
  * the badged person when an acting grant rides the request, otherwise the

package/build/routes/escalations/acting.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACTING_TOKEN_HEADER = void 0;
+exports.ACTING_REMAINING_HEADER = exports.ACTING_TOKEN_HEADER = void 0;
 exports.effectiveWorkAuth = effectiveWorkAuth;
 const acting_identity_1 = require("../../services/iam/acting-identity");
 /** The header a shared station device rides its badge grant on. */
 exports.ACTING_TOKEN_HEADER = 'x-lt-acting-token';
+/**
+ * Uses the grant has left after this request spent one: a count, or
+ * `unbounded` while only the TTL limits it. The client retires its grant on 0.
+ */
+exports.ACTING_REMAINING_HEADER = 'x-lt-acting-remaining';
 /**
  * The effective actor for an escalation WORK verb (claim, release, resolve):
  * the badged person when an acting grant rides the request, otherwise the
@@ -21,5 +26,7 @@ async function effectiveWorkAuth(req, res) {
         res.status(401).json({ error: resolved.error });
         return null;
     }
+    const { remaining } = resolved.grant;
+    res.setHeader(exports.ACTING_REMAINING_HEADER, remaining === null ? 'unbounded' : String(remaining));
     return resolved.auth;
 }

package/build/routes/scan-codes.js

@@ -49,6 +49,8 @@ router.post('/execute', async (req, res) => {
         code: req.body.code,
         actingToken: req.body.actingToken,
         previousActingToken: req.body.previousActingToken,
+        subject: req.body.subject,
+        stationRole: req.body.stationRole,
     }, req.auth);
     res.status(result.status).json(result.data ?? { error: result.error });
 });
@@ -102,6 +104,7 @@ router.put('/schemes/:version', auth_1.requireRoleManager, async (req, res) => {
         kind: req.body.kind,
         grant_ttl_seconds: req.body.grant_ttl_seconds,
         grant_max_uses: req.body.grant_max_uses,
+        grant_scope: req.body.grant_scope,
         enabled: req.body.enabled,
     });
     res.status(result.status).json(result.data ?? { error: result.error });

package/build/services/iam/acting-identity.d.ts

@@ -1,16 +1,41 @@
 import type { LTApiAuth } from '../../types/sdk';
+/** What the client needs to know about a grant after a request touched it. */
+export interface ActingGrantState {
+    /** True when this request spent a use. */
+    consumed: boolean;
+    /** Uses left; null = bounded only by TTL (or bound to one subject). */
+    remaining: number | null;
+    /** True once the grant is bound to one subject. */
+    bound: boolean;
+}
 /** The acting-auth resolution result: an auth to act as, or the loud reason not to. */
 export type ActingAuthResult = {
     ok: true;
     auth: LTApiAuth;
+    grant: ActingGrantState;
 } | {
     ok: false;
     error: string;
 };
+export declare const ACTING_ERRORS: {
+    readonly NOT_A_GRANT: "actingToken is not an acting-identity grant";
+    readonly EXPIRED: "acting identity expired — scan your badge again";
+    readonly INACTIVE: "acting identity is no longer an active user";
+    readonly OTHER_SUBJECT: "this badge already acted on another item; scan your badge again";
+};
+/**
+ * Read a supplied acting grant without spending it. A token that fails
+ * (wrong label, expired, exhausted, or a vanished user) is a terminal error,
+ * never a silent fall-back to the session identity: that would misattribute
+ * whatever follows.
+ */
+export declare function peekActingAuth(actingToken: string): Promise<ActingAuthResult>;
 /**
- * Exchange a supplied acting grant for the person it names. A supplied token
- * that fails — wrong label, expired, exhausted, or a vanished user — is a
- * terminal error, never a silent fall-back to the session identity: that
- * would misattribute whatever follows.
+ * Spend one use of the grant for an act. `ref` names the subject the act
+ * lands on; a subject-scoped grant binds to it on first spend.
  */
+export declare function consumeActingGrant(actingToken: string, ref?: string | null): Promise<ActingAuthResult>;
+/** Return a use whose act missed. `unbind` when that spend bound the grant. */
+export declare function refundActingGrant(actingToken: string, unbind: boolean): Promise<void>;
+/** Spend the grant up front: the escalation work routes always act. */
 export declare function resolveActingAuth(actingToken: string): Promise<ActingAuthResult>;

package/build/services/iam/acting-identity.js

@@ -33,28 +33,71 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTING_ERRORS = void 0;
+exports.peekActingAuth = peekActingAuth;
+exports.consumeActingGrant = consumeActingGrant;
+exports.refundActingGrant = refundActingGrant;
 exports.resolveActingAuth = resolveActingAuth;
 const userService = __importStar(require("../user"));
 const ephemeral_1 = require("./ephemeral");
 const types_1 = require("../../types");
+exports.ACTING_ERRORS = {
+    NOT_A_GRANT: 'actingToken is not an acting-identity grant',
+    EXPIRED: 'acting identity expired — scan your badge again',
+    INACTIVE: 'acting identity is no longer an active user',
+    OTHER_SUBJECT: 'this badge already acted on another item; scan your badge again',
+};
+function isActingGrant(actingToken) {
+    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
+    return parsed && parsed.label === types_1.ACTING_IDENTITY_LABEL ? parsed.uuid : null;
+}
+async function toAuth(grant, consumed) {
+    const user = await userService.getUser(grant.value);
+    if (!user || user.status !== 'active')
+        return { ok: false, error: exports.ACTING_ERRORS.INACTIVE };
+    return {
+        ok: true,
+        auth: { userId: user.id },
+        grant: { consumed, remaining: grant.remaining, bound: grant.bound },
+    };
+}
 /**
- * Exchange a supplied acting grant for the person it names. A supplied token
- * that fails — wrong label, expired, exhausted, or a vanished user — is a
- * terminal error, never a silent fall-back to the session identity: that
- * would misattribute whatever follows.
+ * Read a supplied acting grant without spending it. A token that fails
+ * (wrong label, expired, exhausted, or a vanished user) is a terminal error,
+ * never a silent fall-back to the session identity: that would misattribute
+ * whatever follows.
  */
-async function resolveActingAuth(actingToken) {
-    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
-    if (!parsed || parsed.label !== types_1.ACTING_IDENTITY_LABEL) {
-        return { ok: false, error: 'actingToken is not an acting-identity grant' };
-    }
-    const userId = await (0, ephemeral_1.exchangeEphemeralToken)(actingToken);
-    if (!userId) {
-        return { ok: false, error: 'acting identity expired — scan your badge again' };
-    }
-    const user = await userService.getUser(userId);
-    if (!user || user.status !== 'active') {
-        return { ok: false, error: 'acting identity is no longer an active user' };
+async function peekActingAuth(actingToken) {
+    const uuid = isActingGrant(actingToken);
+    if (!uuid)
+        return { ok: false, error: exports.ACTING_ERRORS.NOT_A_GRANT };
+    const grant = await (0, ephemeral_1.peekEphemeral)(uuid);
+    if (!grant)
+        return { ok: false, error: exports.ACTING_ERRORS.EXPIRED };
+    return toAuth(grant, false);
+}
+/**
+ * Spend one use of the grant for an act. `ref` names the subject the act
+ * lands on; a subject-scoped grant binds to it on first spend.
+ */
+async function consumeActingGrant(actingToken, ref = null) {
+    const uuid = isActingGrant(actingToken);
+    if (!uuid)
+        return { ok: false, error: exports.ACTING_ERRORS.NOT_A_GRANT };
+    const grant = await (0, ephemeral_1.consumeEphemeral)(uuid, ref);
+    if (!grant) {
+        const live = ref ? await (0, ephemeral_1.peekEphemeral)(uuid) : null;
+        return { ok: false, error: live?.bound ? exports.ACTING_ERRORS.OTHER_SUBJECT : exports.ACTING_ERRORS.EXPIRED };
     }
-    return { ok: true, auth: { userId: user.id } };
+    return toAuth(grant, true);
+}
+/** Return a use whose act missed. `unbind` when that spend bound the grant. */
+async function refundActingGrant(actingToken, unbind) {
+    const uuid = isActingGrant(actingToken);
+    if (uuid)
+        await (0, ephemeral_1.refundEphemeral)(uuid, unbind);
+}
+/** Spend the grant up front: the escalation work routes always act. */
+async function resolveActingAuth(actingToken) {
+    return consumeActingGrant(actingToken);
 }

package/build/services/iam/ephemeral.d.ts

@@ -21,6 +21,8 @@ export interface StoreEphemeralOptions {
     ttlSeconds?: number;
     /** Human-readable label for debugging. */
     label?: string;
+    /** The first ref-carrying spend binds the token to that ref (see consumeEphemeral). */
+    bindOnUse?: boolean;
 }
 /**
  * Store a sensitive value. Returns the raw token UUID.
@@ -40,6 +42,25 @@ export declare function storeEphemeral(value: string, opts?: StoreEphemeralOptio
  * - Row is deleted when use_count reaches max_uses (if max_uses > 0)
  */
 export declare function exchangeEphemeral(token: string): Promise<string | null>;
+/** A live token's value and how many uses it has left (null = unbounded). */
+export interface EphemeralGrant {
+    value: string;
+    remaining: number | null;
+    /** True once the token is bound to a ref; it then acts only on that ref. */
+    bound: boolean;
+}
+/** Read a live token without spending a use. */
+export declare function peekEphemeral(token: string): Promise<EphemeralGrant | null>;
+/**
+ * Spend one use of a token. A token stored with `bindOnUse` binds to `ref`
+ * on its first ref-carrying spend; after that it spends freely on that ref
+ * and never on another. Returns null when expired, exhausted, or bound
+ * elsewhere. An exhausted row stays until its TTL so a spend whose act
+ * missed can be refunded.
+ */
+export declare function consumeEphemeral(token: string, ref?: string | null): Promise<EphemeralGrant | null>;
+/** Undo one spend whose act did not land. `unbind` undoes the binding that spend made. */
+export declare function refundEphemeral(token: string, unbind: boolean): Promise<void>;
 /**
  * Explicitly revoke a token before expiry/exhaustion.
  */

package/build/services/iam/ephemeral.js

@@ -7,6 +7,9 @@ exports.exchangeEphemeralToken = exchangeEphemeralToken;
 exports.exchangeTokensInArgs = exchangeTokensInArgs;
 exports.storeEphemeral = storeEphemeral;
 exports.exchangeEphemeral = exchangeEphemeral;
+exports.peekEphemeral = peekEphemeral;
+exports.consumeEphemeral = consumeEphemeral;
+exports.refundEphemeral = refundEphemeral;
 exports.revokeEphemeral = revokeEphemeral;
 exports.cleanupExpired = cleanupExpired;
 const db_1 = require("../../lib/db");
@@ -81,7 +84,7 @@ async function storeEphemeral(value, opts = {}) {
     const expiresAt = opts.ttlSeconds
         ? `NOW() + ${opts.ttlSeconds} * INTERVAL '1 second'`
         : 'NULL';
-    const { rows } = await pool.query((0, sql_1.INSERT_EPHEMERAL)(expiresAt), [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses]);
+    const { rows } = await pool.query((0, sql_1.INSERT_EPHEMERAL)(expiresAt), [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses, opts.bindOnUse ?? false]);
     return rows[0].token;
 }
 /**
@@ -106,6 +109,34 @@ async function exchangeEphemeral(token) {
     }
     return (0, crypto_1.decrypt)(buf.toString('base64'));
 }
+function toGrant(row) {
+    const bound = row.bound_ref !== null;
+    return {
+        value: (0, crypto_1.decrypt)(row.value.toString('base64')),
+        remaining: bound || row.max_uses === 0 ? null : Math.max(0, row.max_uses - row.use_count),
+        bound,
+    };
+}
+/** Read a live token without spending a use. */
+async function peekEphemeral(token) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.PEEK_EPHEMERAL, [token]);
+    return rows.length ? toGrant(rows[0]) : null;
+}
+/**
+ * Spend one use of a token. A token stored with `bindOnUse` binds to `ref`
+ * on its first ref-carrying spend; after that it spends freely on that ref
+ * and never on another. Returns null when expired, exhausted, or bound
+ * elsewhere. An exhausted row stays until its TTL so a spend whose act
+ * missed can be refunded.
+ */
+async function consumeEphemeral(token, ref = null) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.CONSUME_EPHEMERAL, [token, ref]);
+    return rows.length ? toGrant(rows[0]) : null;
+}
+/** Undo one spend whose act did not land. `unbind` undoes the binding that spend made. */
+async function refundEphemeral(token, unbind) {
+    await (0, db_1.getPool)().query(sql_1.REFUND_EPHEMERAL, [token, unbind]);
+}
 /**
  * Explicitly revoke a token before expiry/exhaustion.
  */

package/build/services/iam/sql.d.ts

@@ -1,6 +1,16 @@
 /** Build INSERT for ephemeral credentials. expiresExpr is a SQL expression like 'NULL' or "NOW() + N * INTERVAL '1 second'". */
 export declare const INSERT_EPHEMERAL: (expiresExpr: string) => string;
 export declare const EXCHANGE_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = use_count + 1\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (max_uses = 0 OR use_count < max_uses)\n  RETURNING value, use_count, max_uses";
+/** Validity check without spending a use. A bound grant stays live until its TTL. */
+export declare const PEEK_EPHEMERAL = "\n  SELECT value, use_count, max_uses, bound_ref\n  FROM lt_ephemeral_credentials\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (bound_ref IS NOT NULL OR max_uses = 0 OR use_count < max_uses)";
+/**
+ * Spend one use, binding a bind_on_use grant to $2 on its first spend.
+ * A bound grant acts again on its own ref without counting, and never on
+ * another ref. Without a ref ($2 NULL) the grant counts like any other.
+ */
+export declare const CONSUME_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = CASE WHEN bound_ref IS NOT NULL THEN use_count ELSE use_count + 1 END,\n      bound_ref = CASE WHEN bind_on_use AND bound_ref IS NULL THEN $2::text ELSE bound_ref END\n  WHERE token = $1\n    AND (expires_at IS NULL OR expires_at > NOW())\n    AND (\n      (bound_ref IS NOT NULL AND bound_ref = $2::text)\n      OR (bound_ref IS NULL AND (max_uses = 0 OR use_count < max_uses))\n    )\n  RETURNING value, use_count, max_uses, bound_ref";
+/** Return a use an act spent but did not land; $2 also undoes the binding that spend made. */
+export declare const REFUND_EPHEMERAL = "\n  UPDATE lt_ephemeral_credentials\n  SET use_count = GREATEST(use_count - 1, 0),\n      bound_ref = CASE WHEN $2::boolean THEN NULL ELSE bound_ref END\n  WHERE token = $1";
 export declare const DELETE_EPHEMERAL = "\n  DELETE FROM lt_ephemeral_credentials WHERE token = $1";
 export declare const CLEANUP_EXPIRED_EPHEMERAL = "\n  DELETE FROM lt_ephemeral_credentials\n  WHERE expires_at IS NOT NULL AND expires_at < NOW()";
 export declare const LIST_BOTS = "\n  SELECT * FROM lt_users\n  WHERE account_type = 'bot'\n    AND ($3::text IS NULL OR status = $3)\n    AND ($4::text IS NULL\n      OR display_name ILIKE '%' || $4 || '%'\n      OR external_id ILIKE '%' || $4 || '%'\n      OR metadata->>'description' ILIKE '%' || $4 || '%')\n  ORDER BY created_at DESC\n  LIMIT $1 OFFSET $2";

package/build/services/iam/sql.js

@@ -1,11 +1,11 @@
 "use strict";
 // ─── Ephemeral credentials ──────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET_USER_WITH_ROLES_FLEXIBLE = exports.GET_USER_BY_EXTERNAL_ID = exports.SET_ACCOUNT_TYPE_BOT = exports.COUNT_BOTS = exports.LIST_BOTS = exports.CLEANUP_EXPIRED_EPHEMERAL = exports.DELETE_EPHEMERAL = exports.EXCHANGE_EPHEMERAL = exports.INSERT_EPHEMERAL = void 0;
+exports.GET_USER_WITH_ROLES_FLEXIBLE = exports.GET_USER_BY_EXTERNAL_ID = exports.SET_ACCOUNT_TYPE_BOT = exports.COUNT_BOTS = exports.LIST_BOTS = exports.CLEANUP_EXPIRED_EPHEMERAL = exports.DELETE_EPHEMERAL = exports.REFUND_EPHEMERAL = exports.CONSUME_EPHEMERAL = exports.PEEK_EPHEMERAL = exports.EXCHANGE_EPHEMERAL = exports.INSERT_EPHEMERAL = void 0;
 /** Build INSERT for ephemeral credentials. expiresExpr is a SQL expression like 'NULL' or "NOW() + N * INTERVAL '1 second'". */
 const INSERT_EPHEMERAL = (expiresExpr) => `
-  INSERT INTO lt_ephemeral_credentials (value, label, max_uses, expires_at)
-  VALUES ($1, $2, $3, ${expiresExpr})
+  INSERT INTO lt_ephemeral_credentials (value, label, max_uses, bind_on_use, expires_at)
+  VALUES ($1, $2, $3, $4, ${expiresExpr})
   RETURNING token`;
 exports.INSERT_EPHEMERAL = INSERT_EPHEMERAL;
 exports.EXCHANGE_EPHEMERAL = `
@@ -15,6 +15,35 @@ exports.EXCHANGE_EPHEMERAL = `
     AND (expires_at IS NULL OR expires_at > NOW())
     AND (max_uses = 0 OR use_count < max_uses)
   RETURNING value, use_count, max_uses`;
+/** Validity check without spending a use. A bound grant stays live until its TTL. */
+exports.PEEK_EPHEMERAL = `
+  SELECT value, use_count, max_uses, bound_ref
+  FROM lt_ephemeral_credentials
+  WHERE token = $1
+    AND (expires_at IS NULL OR expires_at > NOW())
+    AND (bound_ref IS NOT NULL OR max_uses = 0 OR use_count < max_uses)`;
+/**
+ * Spend one use, binding a bind_on_use grant to $2 on its first spend.
+ * A bound grant acts again on its own ref without counting, and never on
+ * another ref. Without a ref ($2 NULL) the grant counts like any other.
+ */
+exports.CONSUME_EPHEMERAL = `
+  UPDATE lt_ephemeral_credentials
+  SET use_count = CASE WHEN bound_ref IS NOT NULL THEN use_count ELSE use_count + 1 END,
+      bound_ref = CASE WHEN bind_on_use AND bound_ref IS NULL THEN $2::text ELSE bound_ref END
+  WHERE token = $1
+    AND (expires_at IS NULL OR expires_at > NOW())
+    AND (
+      (bound_ref IS NOT NULL AND bound_ref = $2::text)
+      OR (bound_ref IS NULL AND (max_uses = 0 OR use_count < max_uses))
+    )
+  RETURNING value, use_count, max_uses, bound_ref`;
+/** Return a use an act spent but did not land; $2 also undoes the binding that spend made. */
+exports.REFUND_EPHEMERAL = `
+  UPDATE lt_ephemeral_credentials
+  SET use_count = GREATEST(use_count - 1, 0),
+      bound_ref = CASE WHEN $2::boolean THEN NULL ELSE bound_ref END
+  WHERE token = $1`;
 exports.DELETE_EPHEMERAL = `
   DELETE FROM lt_ephemeral_credentials WHERE token = $1`;
 exports.CLEANUP_EXPIRED_EPHEMERAL = `

package/build/services/role/badge-grant.d.ts

@@ -0,0 +1,5 @@
+import { type RoleBadgeGrant } from './types';
+/** The problem with a `properties.badge_grant` value, or null when it is usable (or absent). */
+export declare function badgeGrantError(value: unknown): string | null;
+/** The role's badge policy from its properties bag, or null when it declares none (or an unusable one). */
+export declare function readBadgeGrant(properties: Record<string, unknown> | null | undefined): RoleBadgeGrant | null;

package/build/services/role/badge-grant.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.badgeGrantError = badgeGrantError;
+exports.readBadgeGrant = readBadgeGrant;
+const types_1 = require("./types");
+const SCOPES = ['action', 'subject'];
+/** The problem with a `properties.badge_grant` value, or null when it is usable (or absent). */
+function badgeGrantError(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'object' || Array.isArray(value))
+        return 'properties.badge_grant must be an object';
+    const grant = value;
+    const known = new Set(['ttl_seconds', 'max_uses', 'scope']);
+    const extra = Object.keys(grant).filter((k) => !known.has(k));
+    if (extra.length)
+        return `properties.badge_grant has unknown key(s): ${extra.join(', ')}`;
+    if (grant.ttl_seconds !== undefined
+        && (!Number.isInteger(grant.ttl_seconds) || grant.ttl_seconds < 1 || grant.ttl_seconds > 86_400)) {
+        return 'properties.badge_grant.ttl_seconds must be an integer from 1 to 86400';
+    }
+    if (grant.max_uses !== undefined && (!Number.isInteger(grant.max_uses) || grant.max_uses < 0)) {
+        return 'properties.badge_grant.max_uses must be a non-negative integer';
+    }
+    if (grant.scope !== undefined && !SCOPES.includes(grant.scope)) {
+        return `properties.badge_grant.scope must be one of ${SCOPES.join(', ')}`;
+    }
+    return null;
+}
+/** The role's badge policy from its properties bag, or null when it declares none (or an unusable one). */
+function readBadgeGrant(properties) {
+    const value = properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT];
+    if (value === undefined || value === null || badgeGrantError(value))
+        return null;
+    return value;
+}

package/build/services/role/seed.js

@@ -8,6 +8,8 @@ const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
 const index_1 = require("./index");
 const sql_1 = require("./sql");
+const badge_grant_1 = require("./badge-grant");
+const types_1 = require("./types");
 /** Recorded on schema snapshots written by the startup apply. */
 exports.STARTUP_CHANGE_SUMMARY = 'startup apply (code)';
 /** Metadata fields shared 1:1 between LTRoleConfig and UpdateRoleInput. */
@@ -79,6 +81,9 @@ async function listConfiguredRoles() {
  * Escalation targets use replace semantics when declared.
  */
 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 created = await (0, index_1.createRole)(cfg.role);
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.GET_ROLE_ROW, [cfg.role]);

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

@@ -15,6 +15,10 @@ export interface EscalationChain {
  *    MEMBER of exactly this one role, the dashboard drops the left nav, the
  *    role's escalation list becomes home, and navigation is held to the list,
  *    the detail page, and the scan screens. Multi-role users get full chrome.
+ *  - BADGE_GRANT: RoleBadgeGrant — the badge policy at this role's stations.
+ *    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).
  *  - 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
@@ -27,7 +31,17 @@ export declare const ROLE_PROPERTY_KEYS: {
     readonly WORKED_BY: "worked_by";
     readonly KIOSK: "kiosk";
     readonly LINK_VARIABLES: "link_variables";
+    readonly BADGE_GRANT: "badge_grant";
 };
+/** 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). */
+    ttl_seconds?: number;
+    /** 0 = TTL-bound; n = the grant covers n acts. */
+    max_uses?: number;
+    /** 'action' spends a use per act; 'subject' binds to one held item. */
+    scope?: 'action' | 'subject';
+}
 /**
  * One link-variable declaration inside `properties.link_variables`. `name` is
  * the metadata facet key (facet-key charset); `label` is the human annotation

package/build/services/role/types.js

@@ -14,6 +14,10 @@ exports.PORTAL_KEY = exports.PORTAL_LIMITS = exports.ROLE_PROPERTY_KEYS = void 0
  *    MEMBER of exactly this one role, the dashboard drops the left nav, the
  *    role's escalation list becomes home, and navigation is held to the list,
  *    the detail page, and the scan screens. Multi-role users get full chrome.
+ *  - BADGE_GRANT: RoleBadgeGrant — the badge policy at this role's stations.
+ *    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).
  *  - 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
@@ -26,6 +30,7 @@ exports.ROLE_PROPERTY_KEYS = {
     WORKED_BY: 'worked_by',
     KIOSK: 'kiosk',
     LINK_VARIABLES: 'link_variables',
+    BADGE_GRANT: 'badge_grant',
 };
 /** 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/index.d.ts

@@ -1,4 +1,5 @@
 export { listScanSchemes, getScanScheme, listScanRules, getScanRule, } from './read';
 export { upsertScanScheme, deleteScanScheme, upsertScanRule, deleteScanRule, seedScanScheme, seedScanRule, applyScanScheme, applyScanRule, type ScanSchemeInput, type ScanRuleInput, } from './write';
-export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
-export { assertValidScheme, assertValidSteps } from './validate';
+export { parseScanCode, interpolateScanTemplate, mentionsClaimToken, renderScanCopy, ScanTemplateError, type ScanParseResult, type ScanParseFailure, type ScanTemplateContext, } from './parse';
+export { assertValidScheme, assertValidSteps, assertValidIdentityRule, assertSchemesCoexist, } from './validate';
+export { isValidGtin, normalizeGtin } from '../../shared/scan-code';

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
+exports.normalizeGtin = exports.isValidGtin = exports.assertSchemesCoexist = exports.assertValidIdentityRule = exports.assertValidSteps = exports.assertValidScheme = exports.ScanTemplateError = exports.renderScanCopy = exports.mentionsClaimToken = exports.interpolateScanTemplate = exports.parseScanCode = exports.applyScanRule = exports.applyScanScheme = exports.seedScanRule = exports.seedScanScheme = exports.deleteScanRule = exports.upsertScanRule = exports.deleteScanScheme = exports.upsertScanScheme = exports.getScanRule = exports.listScanRules = exports.getScanScheme = exports.listScanSchemes = void 0;
 var read_1 = require("./read");
 Object.defineProperty(exports, "listScanSchemes", { enumerable: true, get: function () { return read_1.listScanSchemes; } });
 Object.defineProperty(exports, "getScanScheme", { enumerable: true, get: function () { return read_1.getScanScheme; } });
@@ -19,7 +19,13 @@ var parse_1 = require("./parse");
 Object.defineProperty(exports, "parseScanCode", { enumerable: true, get: function () { return parse_1.parseScanCode; } });
 Object.defineProperty(exports, "interpolateScanTemplate", { enumerable: true, get: function () { return parse_1.interpolateScanTemplate; } });
 Object.defineProperty(exports, "mentionsClaimToken", { enumerable: true, get: function () { return parse_1.mentionsClaimToken; } });
+Object.defineProperty(exports, "renderScanCopy", { enumerable: true, get: function () { return parse_1.renderScanCopy; } });
 Object.defineProperty(exports, "ScanTemplateError", { enumerable: true, get: function () { return parse_1.ScanTemplateError; } });
 var validate_1 = require("./validate");
 Object.defineProperty(exports, "assertValidScheme", { enumerable: true, get: function () { return validate_1.assertValidScheme; } });
 Object.defineProperty(exports, "assertValidSteps", { enumerable: true, get: function () { return validate_1.assertValidSteps; } });
+Object.defineProperty(exports, "assertValidIdentityRule", { enumerable: true, get: function () { return validate_1.assertValidIdentityRule; } });
+Object.defineProperty(exports, "assertSchemesCoexist", { enumerable: true, get: function () { return validate_1.assertSchemesCoexist; } });
+var scan_code_1 = require("../../shared/scan-code");
+Object.defineProperty(exports, "isValidGtin", { enumerable: true, get: function () { return scan_code_1.isValidGtin; } });
+Object.defineProperty(exports, "normalizeGtin", { enumerable: true, get: function () { return scan_code_1.normalizeGtin; } });