@hotmeshio/long-tail 0.30.5 → 0.31.1

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

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_TOKEN_MAX_LENGTH = exports.IDENTITY_TOKEN_MIN_LENGTH = void 0;
 exports.assertValidScheme = assertValidScheme;
 exports.assertSchemesCoexist = assertSchemesCoexist;
 exports.assertValidIdentityRule = assertValidIdentityRule;
@@ -20,6 +21,9 @@ const CHOICE_CODE = /^[A-Za-z0-9_-]{1,32}$/;
  * 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. */
+exports.IDENTITY_TOKEN_MIN_LENGTH = 8;
+exports.IDENTITY_TOKEN_MAX_LENGTH = 64;
 function assertValidScheme(scheme) {
     if (!Number.isInteger(scheme.version) || scheme.version < 10 || scheme.version > 99) {
         throw new Error('scheme version must be a two-digit integer between 10 and 99');
@@ -53,6 +57,12 @@ function assertValidScheme(scheme) {
     if (kind !== types_1.SCAN_SCHEME_KINDS.ACTION && kind !== types_1.SCAN_SCHEME_KINDS.IDENTITY) {
         throw new Error(`unknown scheme kind "${kind}"`);
     }
+    if (kind === types_1.SCAN_SCHEME_KINDS.IDENTITY && encoding === types_1.SCAN_ENCODINGS.DELIMITED && scheme.target_length != null) {
+        const length = scheme.target_length;
+        if (!Number.isInteger(length) || length < exports.IDENTITY_TOKEN_MIN_LENGTH || length > exports.IDENTITY_TOKEN_MAX_LENGTH) {
+            throw new Error(`a delimited identity scheme's target_length (the length of a generated badge) must be ${exports.IDENTITY_TOKEN_MIN_LENGTH} to ${exports.IDENTITY_TOKEN_MAX_LENGTH}`);
+        }
+    }
     if (kind === types_1.SCAN_SCHEME_KINDS.IDENTITY) {
         const ttl = scheme.grant_ttl_seconds;
         if (!Number.isInteger(ttl) || ttl < 1 || ttl > 86_400) {

package/build/services/user/crud.d.ts

@@ -1,5 +1,5 @@
 import type { LTUserRecord, LTRoleType, LTUserStatus } from '../../types';
-import type { CreateUserInput, UpdateUserInput, UserPropertyOps } from './types';
+import type { CreateUserInput, PropertyPatchRecord, UpdateUserInput, UserPropertyOps } from './types';
 export declare function attachRoles(user: any): Promise<LTUserRecord>;
 export declare function createUser(input: CreateUserInput): Promise<LTUserRecord>;
 export declare function getUser(id: string): Promise<LTUserRecord | null>;
@@ -56,6 +56,18 @@ export declare function getIdentityPropertyKeys(): Promise<string[]>;
  * A tripped guard raises UserPropertyConflictError (409).
  */
 export declare function patchUserProperties(id: string, ops: UserPropertyOps): Promise<LTUserRecord | null>;
+/**
+ * The identity keys a patch touches: set, removed, or renamed from or to.
+ */
+export declare function identityKeysTouched(ops: UserPropertyOps): Promise<string[]>;
+/**
+ * patchUserProperties, with an lt_label_jobs row written by the same
+ * statement. Returns the user and the ledger row id; null for an unknown user.
+ */
+export declare function patchUserPropertiesRecorded(id: string, ops: UserPropertyOps, record: PropertyPatchRecord): Promise<{
+    user: LTUserRecord;
+    jobId: string;
+} | null>;
 export declare function deleteUser(id: string): Promise<boolean>;
 export declare function listUsers(filters: {
     role?: string;

package/build/services/user/crud.js

@@ -14,6 +14,8 @@ exports.getUserByMetadataValue = getUserByMetadataValue;
 exports.updateUser = updateUser;
 exports.getIdentityPropertyKeys = getIdentityPropertyKeys;
 exports.patchUserProperties = patchUserProperties;
+exports.identityKeysTouched = identityKeysTouched;
+exports.patchUserPropertiesRecorded = patchUserPropertiesRecorded;
 exports.deleteUser = deleteUser;
 exports.listUsers = listUsers;
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
@@ -159,8 +161,12 @@ async function updateUser(id, input) {
         values.push(await bcryptjs_1.default.hash(input.password, 10));
     }
     if (input.metadata !== undefined) {
-        sets.push(`metadata = $${idx++}`);
-        values.push(JSON.stringify(input.metadata));
+        // Identity bindings the replacement leaves out are kept, read in the same statement.
+        const keysIdx = idx++;
+        const metadataIdx = idx++;
+        sets.push(`metadata = COALESCE((SELECT jsonb_object_agg(k, lt_users.metadata -> k) FROM unnest($${keysIdx}::text[]) AS k ` +
+            `WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? k), '{}'::jsonb) || $${metadataIdx}::jsonb`);
+        values.push(await getIdentityPropertyKeys(), JSON.stringify(input.metadata));
     }
     if (sets.length === 0) {
         return getUser(id);
@@ -215,6 +221,29 @@ async function getIdentityPropertyKeys() {
  * A tripped guard raises UserPropertyConflictError (409).
  */
 async function patchUserProperties(id, ops) {
+    const patched = await runPropertyPatch(id, ops, null);
+    return patched?.user ?? null;
+}
+/**
+ * The identity keys a patch touches: set, removed, or renamed from or to.
+ */
+async function identityKeysTouched(ops) {
+    const keys = new Set([
+        ...Object.keys(ops.set ?? {}),
+        ...(ops.remove ?? []),
+        ...Object.entries(ops.rename ?? {}).flat(),
+    ]);
+    return (await getIdentityPropertyKeys()).filter((k) => keys.has(k));
+}
+/**
+ * patchUserProperties, with an lt_label_jobs row written by the same
+ * statement. Returns the user and the ledger row id; null for an unknown user.
+ */
+async function patchUserPropertiesRecorded(id, ops, record) {
+    const patched = await runPropertyPatch(id, ops, record);
+    return patched ? { user: patched.user, jobId: patched.jobId } : null;
+}
+async function runPropertyPatch(id, ops, record) {
     const set = ops.set ?? {};
     const remove = ops.remove ?? [];
     const rename = ops.rename ?? {};
@@ -258,18 +287,20 @@ async function patchUserProperties(id, ops) {
     const removeAll = [...new Set([...remove, ...renameEntries.map(([prev]) => prev)])];
     const renamePairs = renameEntries.map(([prev, next]) => ({ prev, next }));
     const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(sql_1.PATCH_USER_PROPERTIES, [
-        id,
-        removeAll,
-        JSON.stringify(renamePairs),
-        JSON.stringify(set),
-        JSON.stringify(guard),
-    ]);
-    if (rows[0])
-        return attachRoles(rows[0]);
+    const params = [id, removeAll, JSON.stringify(renamePairs), JSON.stringify(set), JSON.stringify(guard)];
+    const { rows } = record
+        ? await pool.query(sql_1.PATCH_USER_PROPERTIES_RECORDED, [...params, JSON.stringify(record)])
+        : await pool.query(sql_1.PATCH_USER_PROPERTIES, params);
+    if (rows[0]) {
+        const { ledger_id: jobId = null, ...row } = rows[0];
+        return { user: await attachRoles(row), jobId };
+    }
     const exists = await pool.query(sql_1.VERIFY_USER_BY_ID, [id]);
     if (!exists.rows[0])
         return null;
+    if (record?.require_active && exists.rows[0].status !== 'active') {
+        throw new UserPropertyValidationError('identity bindings are issued to active users only');
+    }
     // The user exists, so the identity guard is what blocked the write. Name
     // the first guarded key for the caller; the row was not touched.
     throw new UserPropertyConflictError(Object.keys(guard)[0] ?? 'identity binding');

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

@@ -1,5 +1,6 @@
-export { CreateUserInput, UpdateUserInput, UserPropertyOps, VALID_ROLE_TYPES } from './types';
-export { createUser, getUser, getUserNames, UserNameRecord, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, patchUserProperties, getIdentityPropertyKeys, UserPropertyConflictError, UserPropertyValidationError, deleteUser, listUsers, } from './crud';
+export { CreateUserInput, PropertyPatchRecord, UpdateUserInput, UserPropertyOps, VALID_ROLE_TYPES } from './types';
+export { redactIdentityKeys, setIdentityKeyProtection, identityKeysProtected } from './redact';
+export { createUser, getUser, getUserNames, UserNameRecord, getUserByExternalId, getUserByEmail, getUserByMetadataValue, updateUser, patchUserProperties, patchUserPropertiesRecorded, identityKeysTouched, getIdentityPropertyKeys, UserPropertyConflictError, UserPropertyValidationError, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, grantRoleIfAbsent, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
 export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
 export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';

package/build/services/user/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.UserPropertyValidationError = exports.UserPropertyConflictError = exports.getIdentityPropertyKeys = exports.patchUserProperties = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUserNames = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.PREFERENCES_MAX_BYTES = exports.patchPreferences = exports.getPreferences = exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.grantRoleIfAbsent = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.UserPropertyValidationError = exports.UserPropertyConflictError = exports.getIdentityPropertyKeys = exports.identityKeysTouched = exports.patchUserPropertiesRecorded = exports.patchUserProperties = exports.updateUser = exports.getUserByMetadataValue = exports.getUserByEmail = exports.getUserByExternalId = exports.getUserNames = exports.getUser = exports.createUser = exports.identityKeysProtected = exports.setIdentityKeyProtection = exports.redactIdentityKeys = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
+var redact_1 = require("./redact");
+Object.defineProperty(exports, "redactIdentityKeys", { enumerable: true, get: function () { return redact_1.redactIdentityKeys; } });
+Object.defineProperty(exports, "setIdentityKeyProtection", { enumerable: true, get: function () { return redact_1.setIdentityKeyProtection; } });
+Object.defineProperty(exports, "identityKeysProtected", { enumerable: true, get: function () { return redact_1.identityKeysProtected; } });
 var crud_1 = require("./crud");
 Object.defineProperty(exports, "createUser", { enumerable: true, get: function () { return crud_1.createUser; } });
 Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return crud_1.getUser; } });
@@ -12,6 +16,8 @@ Object.defineProperty(exports, "getUserByEmail", { enumerable: true, get: functi
 Object.defineProperty(exports, "getUserByMetadataValue", { enumerable: true, get: function () { return crud_1.getUserByMetadataValue; } });
 Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return crud_1.updateUser; } });
 Object.defineProperty(exports, "patchUserProperties", { enumerable: true, get: function () { return crud_1.patchUserProperties; } });
+Object.defineProperty(exports, "patchUserPropertiesRecorded", { enumerable: true, get: function () { return crud_1.patchUserPropertiesRecorded; } });
+Object.defineProperty(exports, "identityKeysTouched", { enumerable: true, get: function () { return crud_1.identityKeysTouched; } });
 Object.defineProperty(exports, "getIdentityPropertyKeys", { enumerable: true, get: function () { return crud_1.getIdentityPropertyKeys; } });
 Object.defineProperty(exports, "UserPropertyConflictError", { enumerable: true, get: function () { return crud_1.UserPropertyConflictError; } });
 Object.defineProperty(exports, "UserPropertyValidationError", { enumerable: true, get: function () { return crud_1.UserPropertyValidationError; } });

package/build/services/user/redact.d.ts

@@ -0,0 +1,17 @@
+import type { LTUserRecord } from '../../types';
+/**
+ * Whether identity keys are protected: left out of user reads, refused in
+ * wholesale metadata writes, and written only with credentialIssuer. On by
+ * default; start({ labels: { protectIdentityKeys: false } }) turns it off.
+ */
+export declare function setIdentityKeyProtection(on: boolean): void;
+export declare function identityKeysProtected(): boolean;
+/**
+ * A user record as a reader sees it. `identity_bound` names the identity keys
+ * the user carries; while protection is on, their values (badge tokens and
+ * other printed credentials) leave `metadata`, and printing a credential is
+ * the only path that reveals one.
+ */
+export declare function redactIdentityKeys<T extends Pick<LTUserRecord, 'metadata'>>(user: T, identityKeys: string[]): T & {
+    identity_bound: string[];
+};

package/build/services/user/redact.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setIdentityKeyProtection = setIdentityKeyProtection;
+exports.identityKeysProtected = identityKeysProtected;
+exports.redactIdentityKeys = redactIdentityKeys;
+const config_1 = require("../../modules/config");
+let protectIdentityKeys = config_1.config.LT_PROTECT_IDENTITY_KEYS;
+/**
+ * Whether identity keys are protected: left out of user reads, refused in
+ * wholesale metadata writes, and written only with credentialIssuer. On by
+ * default; start({ labels: { protectIdentityKeys: false } }) turns it off.
+ */
+function setIdentityKeyProtection(on) {
+    protectIdentityKeys = on;
+}
+function identityKeysProtected() {
+    return protectIdentityKeys;
+}
+/**
+ * A user record as a reader sees it. `identity_bound` names the identity keys
+ * the user carries; while protection is on, their values (badge tokens and
+ * other printed credentials) leave `metadata`, and printing a credential is
+ * the only path that reveals one.
+ */
+function redactIdentityKeys(user, identityKeys) {
+    const metadata = user.metadata ? { ...user.metadata } : user.metadata;
+    const bound = identityKeys.filter((key) => !!metadata && key in metadata);
+    if (metadata && protectIdentityKeys)
+        for (const key of bound)
+            delete metadata[key];
+    return { ...user, metadata, identity_bound: bound };
+}

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

@@ -33,23 +33,16 @@ export declare const GET_NAMES_BY_IDS = "SELECT id, display_name, external_id, e
  */
 export declare const GET_USERS_BY_METADATA_VALUE: string;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
-export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
+export declare const VERIFY_USER_BY_ID = "SELECT id, status FROM lt_users WHERE id = $1 LIMIT 1";
+export declare const PATCH_USER_PROPERTIES = "\n  UPDATE lt_users SET metadata = (\n    (COALESCE(metadata, '{}'::jsonb) - $2::text[])\n    || COALESCE((\n      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)\n      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)\n      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev\n    ), '{}'::jsonb)\n    || $4::jsonb\n  )\n  WHERE id = $1\n    AND NOT EXISTS (\n      SELECT 1\n      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)\n      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v\n    )\n  RETURNING *";
 /**
- * Atomic per-key patch of the user's properties dictionary — ONE statement,
- * never read-merge-write. Composition (later wins on key collision):
- *
- *   base minus ($2: removed keys ∪ rename old-names)
- *   || renames ($3: [{prev,next}] — each carries the OLD value, skipped when
- *      the source key is absent)
- *   || sets ($4: typed JSON values)
- *
- * $5 is the identity-binding guard: {key: value} pairs that must not already
- * belong to ANOTHER active user (the write-side counterpart of the
- * resolver's ambiguity throw in GET_USERS_BY_METADATA_VALUE). Zero rows
- * back means the user is missing OR the guard tripped — the caller
- * distinguishes with VERIFY_USER_BY_ID.
+ * The same patch, recorded in lt_label_jobs in the same statement: the ledger
+ * row exists exactly when the patch landed. $6 is the ledger row as JSON
+ * (action, requested_by, source, and for a reissue the template and media);
+ * it never carries the identity value. With `require_active`, only an active
+ * user is patched, checked in the same statement.
  */
-export declare const PATCH_USER_PROPERTIES = "\n  UPDATE lt_users SET metadata = (\n    (COALESCE(metadata, '{}'::jsonb) - $2::text[])\n    || COALESCE((\n      SELECT jsonb_object_agg(r.next, COALESCE(lt_users.metadata, '{}'::jsonb) -> r.prev)\n      FROM jsonb_to_recordset($3::jsonb) AS r(prev text, next text)\n      WHERE COALESCE(lt_users.metadata, '{}'::jsonb) ? r.prev\n    ), '{}'::jsonb)\n    || $4::jsonb\n  )\n  WHERE id = $1\n    AND NOT EXISTS (\n      SELECT 1\n      FROM lt_users u2, jsonb_each_text($5::jsonb) AS g(k, v)\n      WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v\n    )\n  RETURNING *";
+export declare const PATCH_USER_PROPERTIES_RECORDED: string;
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";

package/build/services/user/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.PATCH_USER_PROPERTIES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_NAMES_BY_IDS = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_FOR_AUTH = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = exports.USER_SAFE_COLUMNS_U = exports.USER_SAFE_COLUMNS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.INSERT_USER_ROLE_IF_ABSENT = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.PATCH_USER_PROPERTIES_RECORDED = exports.PATCH_USER_PROPERTIES = exports.VERIFY_USER_BY_ID = exports.GET_USERS_BY_METADATA_VALUE = exports.GET_NAMES_BY_IDS = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_FOR_AUTH = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = exports.USER_SAFE_COLUMNS_U = exports.USER_SAFE_COLUMNS = void 0;
 /**
  * Every lt_users column a client may see. password_hash and oauth_provider_id
  * are credentials and never appear here — no user read path selects them (the
@@ -61,7 +61,7 @@ exports.GET_NAMES_BY_IDS = 'SELECT id, display_name, external_id, email FROM lt_
  */
 exports.GET_USERS_BY_METADATA_VALUE = `SELECT ${exports.USER_SAFE_COLUMNS} FROM lt_users WHERE metadata->>$1 = $2 AND status = 'active' LIMIT 2`;
 /** Check if a user exists by id. Lightweight — returns only the id column. */
-exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
+exports.VERIFY_USER_BY_ID = 'SELECT id, status FROM lt_users WHERE id = $1 LIMIT 1';
 /**
  * Atomic per-key patch of the user's properties dictionary — ONE statement,
  * never read-merge-write. Composition (later wins on key collision):
@@ -77,7 +77,7 @@ exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
  * back means the user is missing OR the guard tripped — the caller
  * distinguishes with VERIFY_USER_BY_ID.
  */
-exports.PATCH_USER_PROPERTIES = `
+const PATCH_USER_PROPERTIES_UPDATE = `
   UPDATE lt_users SET metadata = (
     (COALESCE(metadata, '{}'::jsonb) - $2::text[])
     || COALESCE((
@@ -94,6 +94,30 @@ exports.PATCH_USER_PROPERTIES = `
       WHERE u2.id <> $1 AND u2.status = 'active' AND u2.metadata ->> g.k = g.v
     )
   RETURNING *`;
+exports.PATCH_USER_PROPERTIES = PATCH_USER_PROPERTIES_UPDATE;
+/**
+ * The same patch, recorded in lt_label_jobs in the same statement: the ledger
+ * row exists exactly when the patch landed. $6 is the ledger row as JSON
+ * (action, requested_by, source, and for a reissue the template and media);
+ * it never carries the identity value. With `require_active`, only an active
+ * user is patched, checked in the same statement.
+ */
+exports.PATCH_USER_PROPERTIES_RECORDED = `
+  WITH patched AS (${PATCH_USER_PROPERTIES_UPDATE.replace('WHERE id = $1', "WHERE id = $1 AND (($6::jsonb->>'require_active')::boolean IS NOT TRUE OR status = 'active')")}),
+  recorded AS (
+    INSERT INTO lt_label_jobs (
+      action, requested_by, sensitive, source, subject_user_ids, label_count,
+      template_name, template_revision, template_snapshot, scheme_version, scheme_kind, media, output
+    )
+    SELECT $6::jsonb->>'action', ($6::jsonb->>'requested_by')::uuid, true,
+           COALESCE($6::jsonb->'source', '{}'::jsonb), ARRAY[patched.id],
+           COALESCE(($6::jsonb->>'label_count')::int, 0),
+           $6::jsonb->>'template_name', ($6::jsonb->>'template_revision')::int, $6::jsonb->'template_snapshot',
+           ($6::jsonb->>'scheme_version')::int, $6::jsonb->>'scheme_kind', $6::jsonb->'media', $6::jsonb->>'output'
+    FROM patched
+    RETURNING id
+  )
+  SELECT patched.*, (SELECT id FROM recorded) AS ledger_id FROM patched`;
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
           r.role, r.type AS role_type, r.read_scope, r.write_scope

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

@@ -24,7 +24,10 @@ export interface UpdateUserInput {
     display_name?: string;
     password?: string;
     status?: LTUserStatus;
-    /** Wholesale REPLACE of the properties dictionary — for per-key edits use patchUserProperties. */
+    /**
+     * Wholesale REPLACE of the properties dictionary — for per-key edits use
+     * patchUserProperties. Identity bindings absent from the replacement are kept.
+     */
     metadata?: Record<string, any>;
 }
 /**
@@ -37,3 +40,20 @@ export interface UserPropertyOps {
     remove?: string[];
     rename?: Record<string, string>;
 }
+/** The lt_label_jobs row a recorded property patch writes beside the patch. */
+export interface PropertyPatchRecord {
+    action: 'bind' | 'reissue';
+    requested_by: string;
+    /** Patch only an active user; checked in the patch statement. */
+    require_active?: boolean;
+    /** Which identity keys changed; never their values. */
+    source: Record<string, unknown>;
+    label_count?: number;
+    template_name?: string;
+    template_revision?: number;
+    template_snapshot?: unknown;
+    scheme_version?: number;
+    scheme_kind?: string;
+    media?: unknown;
+    output?: string;
+}

package/build/shared/labels/compose.d.ts

@@ -0,0 +1,12 @@
+import type { ParseableScheme } from '../scan-code/parse';
+/** A code that cannot be composed under its scheme. */
+export declare class ScanComposeError extends Error {
+    constructor(message: string);
+}
+/** Whether the scheme's codes are minted by the engine (and so printable from a template). */
+export declare function isMintableScheme(scheme: Pick<ParseableScheme, 'encoding'>): boolean;
+/**
+ * The code a scan of `target` under `category` reads. Throws ScanComposeError
+ * when the scheme only reads codes (gtin, pattern) or the target does not fit.
+ */
+export declare function composeScanCode(scheme: Pick<ParseableScheme, 'version' | 'encoding' | 'delimiter' | 'target_length'>, category: string, target: string): string;

package/build/shared/labels/compose.js

@@ -0,0 +1,43 @@
+"use strict";
+// The inverse of parseScanCode for the encodings the engine mints.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanComposeError = void 0;
+exports.isMintableScheme = isMintableScheme;
+exports.composeScanCode = composeScanCode;
+/** A code that cannot be composed under its scheme. */
+class ScanComposeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScanComposeError';
+    }
+}
+exports.ScanComposeError = ScanComposeError;
+const PRINTABLE_ASCII = /^[\x21-\x7e]+$/;
+/** Whether the scheme's codes are minted by the engine (and so printable from a template). */
+function isMintableScheme(scheme) {
+    return scheme.encoding === 'fixed' || scheme.encoding === 'delimited';
+}
+/**
+ * The code a scan of `target` under `category` reads. Throws ScanComposeError
+ * when the scheme only reads codes (gtin, pattern) or the target does not fit.
+ */
+function composeScanCode(scheme, category, target) {
+    if (!/^[0-9]$/.test(category)) {
+        throw new ScanComposeError(`category must be a single digit, got "${category}"`);
+    }
+    const version = String(scheme.version);
+    if (scheme.encoding === 'delimited') {
+        if (!target || !PRINTABLE_ASCII.test(target)) {
+            throw new ScanComposeError(`target "${target}" must be printable ASCII with no spaces`);
+        }
+        return `${version}${scheme.delimiter}${category}${scheme.delimiter}${target}`;
+    }
+    if (scheme.encoding === 'fixed') {
+        const length = scheme.target_length ?? 0;
+        if (!new RegExp(`^[0-9]{${length}}$`).test(target)) {
+            throw new ScanComposeError(`target "${target}" must be exactly ${length} digits`);
+        }
+        return `${version}${category}${target}`;
+    }
+    throw new ScanComposeError(`scheme ${version} reads ${scheme.encoding} codes; the engine does not mint them`);
+}

package/build/shared/labels/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types';
+export { composeScanCode, isMintableScheme, ScanComposeError } from './compose';
+export { renderLabelText, listLabelTokens, unknownLabelTokens, userTokenKeys, type LabelTokenContext } from './tokens';
+export { LABEL_MEDIA, DEFAULT_LABEL_MEDIA_ID, LabelMediaError, assertValidMedia, resolveMedia, slotOrigin, slotsPerPage, } from './media';
+export { encodeSymbol, quietZoneModules, SymbolEncodeError, type EncodedSymbol } from './symbol';
+export { layoutLabelContent, GLYPH_ADVANCE, type LabelContentOptions } from './label-content';
+export { buildLabelSheet, cutMarkSegments, LabelLayoutError, MAX_COPIES, type LabelSheetInput } from './layout';
+export { renderSheetSvg, escapeXml, type SvgRenderOptions } from './render-svg';
+export { renderSheetZpl, zplField, ZplRenderError } from './render-zpl';