@hotmeshio/long-tail 0.30.5 → 0.31.0

package/build/services/labels/targets.js

@@ -0,0 +1,216 @@
+"use strict";
+// Resolves a print job's source into targets, reading as the caller.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RANGE_PAD = void 0;
+exports.parseListSource = parseListSource;
+exports.expandRangeSource = expandRangeSource;
+exports.resolveLabelTargets = resolveLabelTargets;
+exports.markResolvedTargets = markResolvedTargets;
+const db_1 = require("../../lib/db");
+const config_1 = require("../../modules/config");
+const types_1 = require("../../types");
+const errors_1 = require("./errors");
+exports.MAX_RANGE_PAD = 12;
+function cap(scheme) {
+    return scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY
+        ? config_1.config.LT_LABELS_MAX_CREDENTIALS_PER_JOB
+        : config_1.config.LT_LABELS_MAX_PER_JOB;
+}
+function assertCount(n, scheme) {
+    if (n === 0)
+        throw new errors_1.LabelRequestError(400, 'the source names no targets');
+    if (n > cap(scheme))
+        throw new errors_1.LabelRequestError(400, `the source names ${n} targets; one job prints at most ${cap(scheme)}`);
+}
+/** Targets from pasted lines or CSV. A first row naming `target` is a header; its columns become item tokens. */
+function parseListSource(text) {
+    const rows = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+        .map((l) => l.split(/[,\t]/).map((c) => c.trim()));
+    if (rows.length === 0)
+        return [];
+    const header = rows[0][0].toLowerCase() === 'target' ? rows.shift().map((h) => h.replace(/[^a-zA-Z0-9_]/g, '_')) : null;
+    return rows.map((cells) => {
+        const item = {};
+        cells.slice(1).forEach((value, i) => { item[header?.[i + 1] || `col${i + 2}`] = value; });
+        return { target: cells[0], item };
+    });
+}
+/** Targets from a numeric run: prefix + zero-padded number + suffix. */
+function expandRangeSource(source, max) {
+    const { from, to, pad = 0, prefix = '', suffix = '' } = source;
+    if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to < from) {
+        throw new errors_1.LabelRequestError(400, 'a range needs whole numbers with from ≤ to');
+    }
+    if (!Number.isInteger(pad) || pad < 0 || pad > exports.MAX_RANGE_PAD) {
+        throw new errors_1.LabelRequestError(400, `pad must be between 0 and ${exports.MAX_RANGE_PAD}`);
+    }
+    if (to - from + 1 > max)
+        throw new errors_1.LabelRequestError(400, `the range names ${to - from + 1} targets; one job prints at most ${max}`);
+    return Array.from({ length: to - from + 1 }, (_, i) => ({
+        target: `${prefix}${String(from + i).padStart(pad, '0')}${suffix}`,
+    }));
+}
+/** Rows read at once for a selection; each read applies the caller's own access check. */
+const ESCALATION_READ_CHUNK = 25;
+async function escalationTargets(ids, scheme, auth) {
+    const { getEscalation } = await Promise.resolve().then(() => __importStar(require('../../api/escalations/single')));
+    const unique = [...new Set(ids)];
+    const byTarget = new Map();
+    for (let i = 0; i < unique.length; i += ESCALATION_READ_CHUNK) {
+        const chunk = unique.slice(i, i + ESCALATION_READ_CHUNK);
+        const results = await Promise.all(chunk.map((id) => getEscalation({ id }, auth)));
+        results.forEach((result, j) => {
+            if (result.status !== 200) {
+                throw new errors_1.LabelRequestError(result.status === 404 ? 404 : 403, `escalation ${chunk[j]}: ${result.error}`);
+            }
+            addRow(byTarget, result.data, scheme);
+        });
+    }
+    return [...byTarget.values()];
+}
+async function facetTargets(source, scheme, auth) {
+    const { searchByFacets } = await Promise.resolve().then(() => __importStar(require('../../api/escalations/facets')));
+    const result = await searchByFacets({ ...source.query, limit: cap(scheme) + 1 }, auth);
+    if (result.status !== 200)
+        throw new errors_1.LabelRequestError(result.status === 400 ? 400 : 403, result.error ?? 'facet search refused');
+    const byTarget = new Map();
+    for (const row of result.data.escalations)
+        addRow(byTarget, row, scheme);
+    return [...byTarget.values()];
+}
+/** Keep the newest row per target; a member facet contributes each of its values. */
+function addRow(byTarget, row, scheme) {
+    const value = row.metadata?.[scheme.target_facet];
+    const values = Array.isArray(value) && scheme.target_match === types_1.SCAN_TARGET_MATCH.MEMBER ? value : [value];
+    for (const v of values) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        const target = String(v);
+        const seen = byTarget.get(target);
+        if (!seen || String(row.created_at) > String(seen.item?.__created_at ?? '')) {
+            byTarget.set(target, { target, item: { ...row.metadata, __created_at: row.created_at }, resolved: true });
+        }
+    }
+}
+const USERS_WITH_KEY = `
+  SELECT u.id FROM lt_users u
+  WHERE u.metadata ? $1
+    AND ($2::uuid[] IS NOT NULL OR u.status = 'active')
+    AND ($2::uuid[] IS NULL OR u.id = ANY($2::uuid[]))
+    AND ($3::text IS NULL OR EXISTS (SELECT 1 FROM lt_user_roles r WHERE r.user_id = u.id AND r.role = $3))
+  ORDER BY u.display_name NULLS LAST, u.external_id
+  LIMIT $4`;
+async function userTargets(source, scheme) {
+    const { getUser, getIdentityPropertyKeys } = await Promise.resolve().then(() => __importStar(require('../user')));
+    const { onlyUuids } = await Promise.resolve().then(() => __importStar(require('../../lib/uuid')));
+    const ids = source.userIds ? onlyUuids(source.userIds) : null;
+    if (source.userIds && ids.length !== new Set(source.userIds).size) {
+        throw new errors_1.LabelRequestError(400, 'userIds must be user ids');
+    }
+    const { rows } = await (0, db_1.getPool)().query(USERS_WITH_KEY, [scheme.target_facet, ids, source.role ?? null, cap(scheme) + 1]);
+    const identityKeys = await getIdentityPropertyKeys();
+    const users = await Promise.all(rows.map((r) => getUser(r.id)));
+    return users.filter((u) => u !== null).map((u) => {
+        const metadata = { ...(u.metadata ?? {}) };
+        for (const key of identityKeys)
+            delete metadata[key];
+        return {
+            target: String(u.metadata[scheme.target_facet]),
+            userId: u.id,
+            resolved: u.status === 'active',
+            user: {
+                ...metadata,
+                name: u.display_name ?? u.external_id,
+                display_name: u.display_name,
+                email: u.email,
+                roles: u.roles.map((r) => r.role),
+            },
+        };
+    });
+}
+/**
+ * The targets a source names. Identity schemes read users only: a pasted or
+ * ranged credential would mint a badge for no one. Rows are read as the
+ * caller, so a job never prints what the caller cannot see.
+ */
+async function resolveLabelTargets(source, scheme, auth) {
+    const identity = scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY;
+    if (identity && source.kind !== 'users') {
+        throw new errors_1.LabelRequestError(400, 'identity labels print for users; use a users source');
+    }
+    if (!identity && source.kind === 'users') {
+        throw new errors_1.LabelRequestError(400, 'a users source prints identity labels only');
+    }
+    let targets;
+    switch (source.kind) {
+        case 'escalations':
+            if (!Array.isArray(source.ids))
+                throw new errors_1.LabelRequestError(400, 'ids must be a list');
+            assertCount(new Set(source.ids).size, scheme);
+            targets = await escalationTargets(source.ids, scheme, auth);
+            break;
+        case 'facets':
+            targets = await facetTargets(source, scheme, auth);
+            break;
+        case 'users':
+            targets = await userTargets(source, scheme);
+            break;
+        case 'list':
+            targets = parseListSource(String(source.text ?? ''));
+            break;
+        case 'range':
+            targets = expandRangeSource(source, cap(scheme));
+            break;
+        default:
+            throw new errors_1.LabelRequestError(400, `unknown source kind "${source.kind}"`);
+    }
+    for (const t of targets)
+        delete t.item?.__created_at;
+    assertCount(targets.length, scheme);
+    return targets;
+}
+/** Marks which action targets name a row today, in one statement. */
+async function markResolvedTargets(targets, scheme) {
+    const unchecked = targets.filter((t) => t.resolved === undefined);
+    if (unchecked.length === 0)
+        return;
+    const member = scheme.target_match === types_1.SCAN_TARGET_MATCH.MEMBER;
+    const { rows } = await (0, db_1.getPool)().query(`SELECT t FROM unnest($2::text[]) AS t
+     WHERE EXISTS (SELECT 1 FROM lt_escalations e WHERE e.metadata @> ${member ? 'jsonb_build_object($1::text, jsonb_build_array(t))' : 'jsonb_build_object($1::text, t)'})`, [scheme.target_facet, unchecked.map((t) => t.target)]);
+    const found = new Set(rows.map((r) => r.t));
+    for (const t of unchecked)
+        t.resolved = found.has(t.target);
+}

package/build/services/labels/templates/index.d.ts

@@ -0,0 +1,3 @@
+export { listLabelTemplates, getLabelTemplate, mapTemplate } from './read';
+export { upsertLabelTemplate, deleteLabelTemplate, seedLabelTemplate, applyLabelTemplate, LabelTemplateConflictError, } from './write';
+export { assertValidTemplate, LabelTemplateValidationError, MAX_TEMPLATE_CODES, MAX_TEMPLATE_LINES, type TemplateContext, } from './validate';

package/build/services/labels/templates/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TEMPLATE_LINES = exports.MAX_TEMPLATE_CODES = exports.LabelTemplateValidationError = exports.assertValidTemplate = exports.LabelTemplateConflictError = exports.applyLabelTemplate = exports.seedLabelTemplate = exports.deleteLabelTemplate = exports.upsertLabelTemplate = exports.mapTemplate = exports.getLabelTemplate = exports.listLabelTemplates = void 0;
+var read_1 = require("./read");
+Object.defineProperty(exports, "listLabelTemplates", { enumerable: true, get: function () { return read_1.listLabelTemplates; } });
+Object.defineProperty(exports, "getLabelTemplate", { enumerable: true, get: function () { return read_1.getLabelTemplate; } });
+Object.defineProperty(exports, "mapTemplate", { enumerable: true, get: function () { return read_1.mapTemplate; } });
+var write_1 = require("./write");
+Object.defineProperty(exports, "upsertLabelTemplate", { enumerable: true, get: function () { return write_1.upsertLabelTemplate; } });
+Object.defineProperty(exports, "deleteLabelTemplate", { enumerable: true, get: function () { return write_1.deleteLabelTemplate; } });
+Object.defineProperty(exports, "seedLabelTemplate", { enumerable: true, get: function () { return write_1.seedLabelTemplate; } });
+Object.defineProperty(exports, "applyLabelTemplate", { enumerable: true, get: function () { return write_1.applyLabelTemplate; } });
+Object.defineProperty(exports, "LabelTemplateConflictError", { enumerable: true, get: function () { return write_1.LabelTemplateConflictError; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "assertValidTemplate", { enumerable: true, get: function () { return validate_1.assertValidTemplate; } });
+Object.defineProperty(exports, "LabelTemplateValidationError", { enumerable: true, get: function () { return validate_1.LabelTemplateValidationError; } });
+Object.defineProperty(exports, "MAX_TEMPLATE_CODES", { enumerable: true, get: function () { return validate_1.MAX_TEMPLATE_CODES; } });
+Object.defineProperty(exports, "MAX_TEMPLATE_LINES", { enumerable: true, get: function () { return validate_1.MAX_TEMPLATE_LINES; } });

package/build/services/labels/templates/read.d.ts

@@ -0,0 +1,4 @@
+import type { LabelTemplate } from '../../../types/labels';
+export declare function mapTemplate(row: any): LabelTemplate;
+export declare function listLabelTemplates(schemeVersion?: number): Promise<LabelTemplate[]>;
+export declare function getLabelTemplate(name: string): Promise<LabelTemplate | null>;

package/build/services/labels/templates/read.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapTemplate = mapTemplate;
+exports.listLabelTemplates = listLabelTemplates;
+exports.getLabelTemplate = getLabelTemplate;
+const db_1 = require("../../../lib/db");
+const sql_1 = require("./sql");
+function mapTemplate(row) {
+    return {
+        name: row.name,
+        scheme_version: row.scheme_version,
+        title: row.title,
+        description: row.description ?? null,
+        codes: row.codes ?? [],
+        text: row.text ?? {},
+        symbology: row.symbology,
+        human_readable: row.human_readable,
+        media: row.media ?? null,
+        sensitive: row.sensitive,
+        enabled: row.enabled,
+        revision: row.revision,
+        source: row.source,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+    };
+}
+async function listLabelTemplates(schemeVersion) {
+    const { rows } = schemeVersion === undefined
+        ? await (0, db_1.getPool)().query(sql_1.LIST_TEMPLATES)
+        : await (0, db_1.getPool)().query(sql_1.LIST_TEMPLATES_BY_SCHEME, [schemeVersion]);
+    return rows.map(mapTemplate);
+}
+async function getLabelTemplate(name) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_TEMPLATE, [name]);
+    return rows[0] ? mapTemplate(rows[0]) : null;
+}

package/build/services/labels/templates/sql.d.ts

@@ -0,0 +1,8 @@
+export declare const LIST_TEMPLATES = "SELECT * FROM lt_config_label_templates ORDER BY scheme_version, name";
+export declare const LIST_TEMPLATES_BY_SCHEME = "SELECT * FROM lt_config_label_templates WHERE scheme_version = $1 ORDER BY name";
+export declare const GET_TEMPLATE = "SELECT * FROM lt_config_label_templates WHERE name = $1";
+export declare const DELETE_TEMPLATE = "DELETE FROM lt_config_label_templates WHERE name = $1";
+/** API write. $13 is the expected revision; null writes unconditionally. */
+export declare const UPSERT_TEMPLATE = "INSERT INTO lt_config_label_templates (name, scheme_version, title, description, codes, text, symbology,\n   human_readable, media, sensitive, enabled, source)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (name) DO UPDATE SET scheme_version = EXCLUDED.scheme_version,\n  title = EXCLUDED.title,\n  description = EXCLUDED.description,\n  codes = EXCLUDED.codes,\n  text = EXCLUDED.text,\n  symbology = EXCLUDED.symbology,\n  human_readable = EXCLUDED.human_readable,\n  media = EXCLUDED.media,\n  sensitive = EXCLUDED.sensitive,\n  enabled = EXCLUDED.enabled,\n  source = EXCLUDED.source,\n  revision = lt_config_label_templates.revision + 1\nWHERE $13::int IS NULL OR lt_config_label_templates.revision = $13::int\nRETURNING *";
+export declare const SEED_TEMPLATE = "INSERT INTO lt_config_label_templates (name, scheme_version, title, description, codes, text, symbology,\n   human_readable, media, sensitive, enabled, source)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (name) DO NOTHING";
+export declare const APPLY_TEMPLATE = "INSERT INTO lt_config_label_templates (name, scheme_version, title, description, codes, text, symbology,\n   human_readable, media, sensitive, enabled, source)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)\nON CONFLICT (name) DO UPDATE SET scheme_version = EXCLUDED.scheme_version,\n  title = EXCLUDED.title,\n  description = EXCLUDED.description,\n  codes = EXCLUDED.codes,\n  text = EXCLUDED.text,\n  symbology = EXCLUDED.symbology,\n  human_readable = EXCLUDED.human_readable,\n  media = EXCLUDED.media,\n  sensitive = EXCLUDED.sensitive,\n  enabled = EXCLUDED.enabled,\n  source = EXCLUDED.source,\n  revision = lt_config_label_templates.revision + 1\nWHERE (lt_config_label_templates.scheme_version, lt_config_label_templates.title,\n       lt_config_label_templates.description, lt_config_label_templates.codes,\n       lt_config_label_templates.text, lt_config_label_templates.symbology,\n       lt_config_label_templates.human_readable, lt_config_label_templates.media,\n       lt_config_label_templates.sensitive, lt_config_label_templates.enabled,\n       lt_config_label_templates.source)\n  IS DISTINCT FROM\n      (EXCLUDED.scheme_version, EXCLUDED.title, EXCLUDED.description, EXCLUDED.codes,\n       EXCLUDED.text, EXCLUDED.symbology, EXCLUDED.human_readable, EXCLUDED.media,\n       EXCLUDED.sensitive, EXCLUDED.enabled, EXCLUDED.source)\nRETURNING (xmax = 0) AS inserted";

package/build/services/labels/templates/sql.js

@@ -0,0 +1,50 @@
+"use strict";
+// lt_config_label_templates. Writes bump `revision`; the apply pass is a
+// zero-row no-op when the declaration is unchanged.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLY_TEMPLATE = exports.SEED_TEMPLATE = exports.UPSERT_TEMPLATE = exports.DELETE_TEMPLATE = exports.GET_TEMPLATE = exports.LIST_TEMPLATES_BY_SCHEME = exports.LIST_TEMPLATES = void 0;
+const COLUMNS = `name, scheme_version, title, description, codes, text, symbology,
+   human_readable, media, sensitive, enabled, source`;
+const VALUES = '$1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12';
+const SET = `scheme_version = EXCLUDED.scheme_version,
+  title = EXCLUDED.title,
+  description = EXCLUDED.description,
+  codes = EXCLUDED.codes,
+  text = EXCLUDED.text,
+  symbology = EXCLUDED.symbology,
+  human_readable = EXCLUDED.human_readable,
+  media = EXCLUDED.media,
+  sensitive = EXCLUDED.sensitive,
+  enabled = EXCLUDED.enabled,
+  source = EXCLUDED.source,
+  revision = lt_config_label_templates.revision + 1`;
+exports.LIST_TEMPLATES = 'SELECT * FROM lt_config_label_templates ORDER BY scheme_version, name';
+exports.LIST_TEMPLATES_BY_SCHEME = 'SELECT * FROM lt_config_label_templates WHERE scheme_version = $1 ORDER BY name';
+exports.GET_TEMPLATE = 'SELECT * FROM lt_config_label_templates WHERE name = $1';
+exports.DELETE_TEMPLATE = 'DELETE FROM lt_config_label_templates WHERE name = $1';
+/** API write. $13 is the expected revision; null writes unconditionally. */
+exports.UPSERT_TEMPLATE = `\
+INSERT INTO lt_config_label_templates (${COLUMNS})
+VALUES (${VALUES})
+ON CONFLICT (name) DO UPDATE SET ${SET}
+WHERE $13::int IS NULL OR lt_config_label_templates.revision = $13::int
+RETURNING *`;
+exports.SEED_TEMPLATE = `\
+INSERT INTO lt_config_label_templates (${COLUMNS})
+VALUES (${VALUES})
+ON CONFLICT (name) DO NOTHING`;
+exports.APPLY_TEMPLATE = `\
+INSERT INTO lt_config_label_templates (${COLUMNS})
+VALUES (${VALUES})
+ON CONFLICT (name) DO UPDATE SET ${SET}
+WHERE (lt_config_label_templates.scheme_version, lt_config_label_templates.title,
+       lt_config_label_templates.description, lt_config_label_templates.codes,
+       lt_config_label_templates.text, lt_config_label_templates.symbology,
+       lt_config_label_templates.human_readable, lt_config_label_templates.media,
+       lt_config_label_templates.sensitive, lt_config_label_templates.enabled,
+       lt_config_label_templates.source)
+  IS DISTINCT FROM
+      (EXCLUDED.scheme_version, EXCLUDED.title, EXCLUDED.description, EXCLUDED.codes,
+       EXCLUDED.text, EXCLUDED.symbology, EXCLUDED.human_readable, EXCLUDED.media,
+       EXCLUDED.sensitive, EXCLUDED.enabled, EXCLUDED.source)
+RETURNING (xmax = 0) AS inserted`;

package/build/services/labels/templates/validate.d.ts

@@ -0,0 +1,19 @@
+import { type ScanRule, type ScanScheme } from '../../../types';
+import type { LabelTemplateInput } from '../../../types/labels';
+/** A template declaration that cannot be stored. */
+export declare class LabelTemplateValidationError extends Error {
+    status: number;
+    constructor(message: string);
+}
+export declare const MAX_TEMPLATE_CODES = 4;
+export declare const MAX_TEMPLATE_LINES = 2;
+export interface TemplateContext {
+    scheme: ScanScheme | null;
+    rules: ScanRule[];
+    /** Every identity key in use, so a token can never print a credential as text. */
+    identityKeys: string[];
+    /** Media preset ids the deployment knows. */
+    mediaIds: string[];
+}
+/** Throws LabelTemplateValidationError unless the template fits its scheme. */
+export declare function assertValidTemplate(input: LabelTemplateInput, ctx: TemplateContext): void;

package/build/services/labels/templates/validate.js

@@ -0,0 +1,93 @@
+"use strict";
+// Template validation against its scheme, its rules and the identity keys.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TEMPLATE_LINES = exports.MAX_TEMPLATE_CODES = exports.LabelTemplateValidationError = void 0;
+exports.assertValidTemplate = assertValidTemplate;
+const types_1 = require("../../../shared/labels/types");
+const compose_1 = require("../../../shared/labels/compose");
+const tokens_1 = require("../../../shared/labels/tokens");
+const types_2 = require("../../../types");
+/** A template declaration that cannot be stored. */
+class LabelTemplateValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.status = 400;
+        this.name = 'LabelTemplateValidationError';
+    }
+}
+exports.LabelTemplateValidationError = LabelTemplateValidationError;
+exports.MAX_TEMPLATE_CODES = 4;
+exports.MAX_TEMPLATE_LINES = 2;
+const MAX_TEXT_LENGTH = 160;
+const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+function fail(message) {
+    throw new LabelTemplateValidationError(message);
+}
+function assertText(label, text) {
+    if (typeof text !== 'string')
+        fail(`${label} must be text`);
+    if (text.length > MAX_TEXT_LENGTH)
+        fail(`${label} is longer than ${MAX_TEXT_LENGTH} characters`);
+}
+/** Throws LabelTemplateValidationError unless the template fits its scheme. */
+function assertValidTemplate(input, ctx) {
+    if (typeof input.name !== 'string' || !NAME.test(input.name)) {
+        fail('name must be lowercase letters, digits and dashes, starting with a letter or digit');
+    }
+    const { scheme } = ctx;
+    if (!scheme)
+        fail(`scan scheme ${input.scheme_version} does not exist`);
+    if (!(0, compose_1.isMintableScheme)(scheme)) {
+        fail(`scheme ${scheme.version} reads ${scheme.encoding} codes; templates print fixed and delimited codes only`);
+    }
+    if (!input.title || typeof input.title !== 'string')
+        fail('title is required');
+    assertText('title', input.title);
+    if (input.description != null)
+        assertText('description', input.description);
+    if (!Array.isArray(input.codes) || input.codes.length < 1 || input.codes.length > exports.MAX_TEMPLATE_CODES) {
+        fail(`a template prints 1 to ${exports.MAX_TEMPLATE_CODES} codes`);
+    }
+    const categories = new Set();
+    for (const code of input.codes) {
+        if (!ctx.rules.some((r) => r.category === code.category)) {
+            fail(`scheme ${scheme.version} has no rule for category "${code.category}"`);
+        }
+        if (categories.has(code.category))
+            fail(`category "${code.category}" is printed twice`);
+        categories.add(code.category);
+        if (!types_1.LABEL_TONES.includes(code.tone))
+            fail(`tone must be one of ${types_1.LABEL_TONES.join(', ')}`);
+        if (code.caption != null)
+            assertText('caption', code.caption);
+    }
+    const lines = input.text?.lines ?? [];
+    if (!Array.isArray(lines) || lines.length > exports.MAX_TEMPLATE_LINES)
+        fail(`a template prints up to ${exports.MAX_TEMPLATE_LINES} lines`);
+    const texts = [input.text?.title ?? '', ...lines, ...input.codes.map((c) => c.caption ?? '')];
+    texts.forEach((t, i) => assertText(i === 0 ? 'text title' : 'text line', t));
+    const identity = scheme.kind === types_2.SCAN_SCHEME_KINDS.IDENTITY;
+    for (const text of texts) {
+        const unknown = (0, tokens_1.unknownLabelTokens)(text);
+        if (unknown.length)
+            fail(`unknown token {${unknown[0]}}; use {target}, {item.<facet>}, {user.<key>} or {scheme.name}`);
+        const tokens = (0, tokens_1.listLabelTokens)(text);
+        if (identity && tokens.some((t) => t.startsWith('item.')))
+            fail('an identity template reads {user.<key>} tokens, not {item.<facet>}');
+        if (!identity && tokens.some((t) => t.startsWith('user.')))
+            fail('{user.<key>} tokens print on identity templates only');
+        const credential = (0, tokens_1.userTokenKeys)(text).find((k) => ctx.identityKeys.includes(k) || k === scheme.target_facet);
+        if (credential)
+            fail(`{user.${credential}} is an identity credential and never prints as text`);
+        if (identity && tokens.includes('target'))
+            fail('{target} on an identity template is the credential; it never prints as text');
+    }
+    const symbology = input.symbology ?? 'code128';
+    if (!types_1.LABEL_SYMBOLOGIES.includes(symbology)) {
+        fail(`symbology must be one of ${types_1.LABEL_SYMBOLOGIES.join(', ')}`);
+    }
+    if (input.media != null && !ctx.mediaIds.includes(input.media))
+        fail(`unknown media "${input.media}"`);
+    if (identity && input.sensitive === false)
+        fail('a template on an identity scheme is always sensitive');
+}

package/build/services/labels/templates/write.d.ts

@@ -0,0 +1,16 @@
+import type { LabelTemplate, LabelTemplateInput } from '../../../types/labels';
+/** An API write raced another: the stored revision is not the one the caller read. */
+export declare class LabelTemplateConflictError extends Error {
+    status: number;
+    constructor(name: string, revision: number);
+}
+/**
+ * Create or replace a template from the API. With `expectedRevision`, the
+ * write lands only on that revision; otherwise LabelTemplateConflictError.
+ */
+export declare function upsertLabelTemplate(input: LabelTemplateInput, expectedRevision?: number): Promise<LabelTemplate>;
+export declare function deleteLabelTemplate(name: string): Promise<boolean>;
+/** Insert a template only when absent (database-owned configuration). */
+export declare function seedLabelTemplate(input: LabelTemplateInput): Promise<boolean>;
+/** Apply a template declared in code; unchanged declarations write nothing. */
+export declare function applyLabelTemplate(input: LabelTemplateInput): Promise<'applied' | 'unchanged'>;

package/build/services/labels/templates/write.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelTemplateConflictError = void 0;
+exports.upsertLabelTemplate = upsertLabelTemplate;
+exports.deleteLabelTemplate = deleteLabelTemplate;
+exports.seedLabelTemplate = seedLabelTemplate;
+exports.applyLabelTemplate = applyLabelTemplate;
+const db_1 = require("../../../lib/db");
+const types_1 = require("../../../types");
+const scan_code_1 = require("../../scan-code");
+const user_1 = require("../../user");
+const media_1 = require("../media");
+const read_1 = require("./read");
+const sql_1 = require("./sql");
+const validate_1 = require("./validate");
+/** An API write raced another: the stored revision is not the one the caller read. */
+class LabelTemplateConflictError extends Error {
+    constructor(name, revision) {
+        super(`label template "${name}" changed (now revision ${revision}); reload and try again`);
+        this.status = 409;
+        this.name = 'LabelTemplateConflictError';
+    }
+}
+exports.LabelTemplateConflictError = LabelTemplateConflictError;
+async function validated(input) {
+    const [scheme, rules, identityKeys] = await Promise.all([
+        (0, scan_code_1.getScanScheme)(input.scheme_version),
+        (0, scan_code_1.listScanRules)(input.scheme_version),
+        (0, user_1.getIdentityPropertyKeys)(),
+    ]);
+    (0, validate_1.assertValidTemplate)(input, { scheme, rules, identityKeys, mediaIds: (0, media_1.labelMediaPresets)().map((m) => m.id) });
+    return { ...input, sensitive: scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY || !!input.sensitive };
+}
+function params(input, source) {
+    return [
+        input.name,
+        input.scheme_version,
+        input.title,
+        input.description ?? null,
+        JSON.stringify(input.codes.map((c) => ({ category: c.category, caption: c.caption ?? null, tone: c.tone }))),
+        JSON.stringify({ title: input.text?.title ?? '', lines: input.text?.lines ?? [] }),
+        input.symbology ?? 'code128',
+        input.human_readable ?? true,
+        input.media ?? null,
+        input.sensitive,
+        input.enabled ?? true,
+        source,
+    ];
+}
+/**
+ * Create or replace a template from the API. With `expectedRevision`, the
+ * write lands only on that revision; otherwise LabelTemplateConflictError.
+ */
+async function upsertLabelTemplate(input, expectedRevision) {
+    const row = await validated(input);
+    const { rows } = await (0, db_1.getPool)().query(sql_1.UPSERT_TEMPLATE, [...params(row, 'api'), expectedRevision ?? null]);
+    if (rows[0])
+        return (0, read_1.mapTemplate)(rows[0]);
+    const current = await (0, db_1.getPool)().query(sql_1.GET_TEMPLATE, [input.name]);
+    throw new LabelTemplateConflictError(input.name, current.rows[0]?.revision ?? 0);
+}
+async function deleteLabelTemplate(name) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.DELETE_TEMPLATE, [name]);
+    return (rowCount ?? 0) > 0;
+}
+/** Insert a template only when absent (database-owned configuration). */
+async function seedLabelTemplate(input) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.SEED_TEMPLATE, params(await validated(input), 'api'));
+    return (rowCount ?? 0) > 0;
+}
+/** Apply a template declared in code; unchanged declarations write nothing. */
+async function applyLabelTemplate(input) {
+    const { rowCount } = await (0, db_1.getPool)().query(sql_1.APPLY_TEMPLATE, params(await validated(input), 'code'));
+    return (rowCount ?? 0) > 0 ? 'applied' : 'unchanged';
+}

package/build/services/labels/token.d.ts

@@ -0,0 +1,9 @@
+import type { ScanScheme } from '../../types';
+/** Characters in a minted delimited credential when the scheme sets no target_length (about 50 bits). */
+export declare const DEFAULT_IDENTITY_TOKEN_LENGTH = 10;
+/**
+ * A random credential for the scheme: Crockford base32 of the scheme's
+ * target_length (default 10) when delimited, that many digits when fixed.
+ * The scheme prefix is added when the code is composed, never stored.
+ */
+export declare function mintIdentityToken(scheme: Pick<ScanScheme, 'encoding' | 'target_length'>): string;

package/build/services/labels/token.js

@@ -0,0 +1,28 @@
+"use strict";
+// New identity credentials, minted to fit the scheme's encoding.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IDENTITY_TOKEN_LENGTH = void 0;
+exports.mintIdentityToken = mintIdentityToken;
+const crypto_1 = require("crypto");
+const errors_1 = require("./errors");
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Characters in a minted delimited credential when the scheme sets no target_length (about 50 bits). */
+exports.DEFAULT_IDENTITY_TOKEN_LENGTH = 10;
+/**
+ * A random credential for the scheme: Crockford base32 of the scheme's
+ * target_length (default 10) when delimited, that many digits when fixed.
+ * The scheme prefix is added when the code is composed, never stored.
+ */
+function mintIdentityToken(scheme) {
+    if (scheme.encoding === 'delimited') {
+        const bytes = (0, crypto_1.randomBytes)(scheme.target_length ?? exports.DEFAULT_IDENTITY_TOKEN_LENGTH);
+        return Array.from(bytes, (b) => CROCKFORD[b % 32]).join('');
+    }
+    if (scheme.encoding === 'fixed') {
+        const length = scheme.target_length ?? 0;
+        if (length < 1)
+            throw new errors_1.LabelRequestError(400, 'the scheme has no target length');
+        return Array.from({ length }, () => String((0, crypto_1.randomInt)(10))).join('');
+    }
+    throw new errors_1.LabelRequestError(400, `credentials are minted for fixed and delimited schemes, not ${scheme.encoding}`);
+}

package/build/services/labels/verify.d.ts

@@ -0,0 +1,4 @@
+import { type ScanRule, type ScanScheme } from '../../types';
+import type { LabelContent, LabelWarning } from '../../shared/labels/types';
+import type { LabelTarget, LabelTemplate } from '../../types/labels';
+export declare function verifyLabels(template: LabelTemplate, scheme: ScanScheme, schemes: ScanScheme[], rules: ScanRule[], targets: LabelTarget[], contents: LabelContent[]): LabelWarning[];

package/build/services/labels/verify.js

@@ -0,0 +1,38 @@
+"use strict";
+// Flags labels that would fail on the floor: a code that does not parse back,
+// a disabled rule or scheme, or a target that names nothing today.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyLabels = verifyLabels;
+const parse_1 = require("../../shared/scan-code/parse");
+const types_1 = require("../../types");
+function verifyLabels(template, scheme, schemes, rules, targets, contents) {
+    const identity = scheme.kind === types_1.SCAN_SCHEME_KINDS.IDENTITY;
+    const warnings = [];
+    if (!scheme.enabled) {
+        contents.forEach((_c, index) => warnings.push({ index, kind: 'unparseable', detail: `scheme ${scheme.version} is disabled; its codes do not scan` }));
+        return warnings;
+    }
+    const disabled = template.codes.filter((c) => !rules.find((r) => r.category === c.category)?.enabled);
+    contents.forEach((content, index) => {
+        for (const c of disabled) {
+            warnings.push({ index, kind: 'rule_disabled', detail: `the rule for category ${c.category} is disabled; that code does nothing when scanned` });
+        }
+        for (const { code } of content.codes) {
+            const parsed = (0, parse_1.parseScanCode)(code, schemes);
+            const same = parsed.ok && parsed.parsed.version === scheme.version && parsed.parsed.target === targets[index].target;
+            if (!same) {
+                warnings.push({
+                    index, kind: 'unparseable',
+                    detail: identity ? 'a badge code does not read back as this scheme' : `${code} does not read back as scheme ${scheme.version}`,
+                });
+            }
+        }
+        if (targets[index].resolved === false) {
+            warnings.push({
+                index, kind: 'unresolved',
+                detail: identity ? 'the badge holder is not an active user' : `${targets[index].target} names no row today`,
+            });
+        }
+    });
+    return warnings;
+}

package/build/services/scan-code/validate.d.ts

@@ -4,6 +4,9 @@ import { type ScanScheme, type ScanStep } from '../../types';
  * problem — a bad scheme silently misparsing every scan is far worse
  * than a loud upsert failure.
  */
+/** Generated badges on a delimited identity scheme: long enough to resist guessing, short enough to scan. */
+export declare const IDENTITY_TOKEN_MIN_LENGTH = 8;
+export declare const IDENTITY_TOKEN_MAX_LENGTH = 64;
 export declare function assertValidScheme(scheme: Partial<ScanScheme>): void;
 /**
  * A scheme must read codes no other scheme reads. Delimited and fixed