@astram/identity 0.3.1 → 0.5.0

package/dist/features/service-account/service-account.service.js

@@ -0,0 +1,528 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceAccountService = exports.ServiceAccountInputError = exports.ServiceAccountConflictError = exports.ServiceAccountCeilingError = exports.ServiceAccountNotFoundError = void 0;
+exports.ceilingOf = ceilingOf;
+exports.ceilingAllowsNode = ceilingAllowsNode;
+exports.ceilingAllowsRole = ceilingAllowsRole;
+/**
+ * ServiceAccountService — the business logic for the Service Accounts admin surface (ADR-0033):
+ * create/edit machine accounts and issue/rotate/revoke their `ask_…` API keys.
+ *
+ * SECURITY (the invariants this service upholds):
+ *  - OWN-TENANT ONLY: every read/update runs through {@link ServiceAccountStore}'s subtree wall; a
+ *    cross-tenant id is NOT FOUND (the service throws {@link ServiceAccountNotFoundError} → 404, no
+ *    existence leak). `sa_tenant_id` is server-stamped from the admin's session on create.
+ *  - CEILING (ADR-0029, least privilege): a NON-ROOT admin may only grant an account a SCOPE that is
+ *    ⊆ their own reachable subtree, and ROLES that are ⊆ the roles they themselves hold — an admin
+ *    cannot mint an agent more powerful than themselves. Root bypasses (spans all).
+ *  - HASH-ONLY KEYS: a key's secret is high-entropy random, hashed via the injected PasswordHasher
+ *    (Argon2id) before it touches the store; the RAW key `ask_<id>_<secret>` is returned to the
+ *    caller EXACTLY ONCE (at issue/rotate) and never stored, logged, or audited.
+ *  - AUDITED: create/update/issue/rotate/revoke each emit an audit event (account id + key version,
+ *    NEVER the secret). Best-effort — an audit failure never fails a legitimate operation.
+ */
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@astram/core");
+/** The account id was not in the caller's subtree (unknown or cross-tenant) → 404 (no leak). */
+class ServiceAccountNotFoundError extends Error {
+    constructor() {
+        super('service account not found');
+        this.name = 'ServiceAccountNotFoundError';
+    }
+}
+exports.ServiceAccountNotFoundError = ServiceAccountNotFoundError;
+/** The requested scope/roles exceed the caller's own authority (ADR-0029) → 403. */
+class ServiceAccountCeilingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServiceAccountCeilingError';
+    }
+}
+exports.ServiceAccountCeilingError = ServiceAccountCeilingError;
+/** The account changed between this edit's read and its write (a concurrent edit) → 409. */
+class ServiceAccountConflictError extends Error {
+    constructor() {
+        super('This agent was changed by someone else just now — reload and try again.');
+        this.name = 'ServiceAccountConflictError';
+    }
+}
+exports.ServiceAccountConflictError = ServiceAccountConflictError;
+/** A malformed request (empty label, no fields to update, etc.) → 400. */
+class ServiceAccountInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServiceAccountInputError';
+    }
+}
+exports.ServiceAccountInputError = ServiceAccountInputError;
+const SECRET_BYTES = 32; // 256-bit secret; base64url ≈ 43 chars
+/** A high-entropy, URL-safe secret for a new key. */
+function mintSecret() {
+    return (0, node_crypto_1.randomBytes)(SECRET_BYTES).toString('base64url');
+}
+/** The admin's own reachable subtree as a SubtreeScope for the store's wall. */
+function scopeOf(admin) {
+    const nodeIds = admin.scopeSubtreeNodeIds.length ? admin.scopeSubtreeNodeIds : [admin.tenantId];
+    return { nodeIds, isRoot: admin.isRoot === true };
+}
+function ceilingOf(admin, heldRoleIds) {
+    return {
+        isRoot: admin.isRoot === true,
+        nodeIds: new Set(scopeOf(admin).nodeIds),
+        roleIds: new Set(heldRoleIds),
+    };
+}
+function ceilingAllowsNode(c, nodeId) {
+    return c.isRoot || c.nodeIds.has(nodeId);
+}
+function ceilingAllowsRole(c, roleId) {
+    return c.isRoot || c.roleIds.has(roleId);
+}
+/** Dedupe an id list keeping first-seen order (drops empty strings). */
+function uniqueIds(ids) {
+    return [...new Set(ids.filter((x) => typeof x === 'string' && x.length > 0))];
+}
+/** `requested` then the `preserved` ids not already in it (first-seen order, no duplicates). */
+function mergeIds(requested, preserved) {
+    return uniqueIds([...requested, ...preserved]);
+}
+/**
+ * Order nodes depth-first (parent before children, siblings by name) and drop any `parentId` that
+ * is not itself in the set (a non-root admin's top node shows as a root — and no out-of-ceiling
+ * handle leaves the server). Cycle-safe: each node is emitted once.
+ */
+function treeOrder(nodes) {
+    const ids = new Set(nodes.map((n) => n.id));
+    const norm = nodes.map((n) => ({
+        id: n.id,
+        name: n.name,
+        parentId: n.parentId !== null && ids.has(n.parentId) && n.parentId !== n.id ? n.parentId : null,
+    }));
+    const byName = (a, b) => a.name.localeCompare(b.name);
+    const children = new Map();
+    for (const n of norm) {
+        const list = children.get(n.parentId) ?? [];
+        list.push(n);
+        children.set(n.parentId, list);
+    }
+    for (const list of children.values())
+        list.sort(byName);
+    const out = [];
+    const seen = new Set();
+    const visit = (n) => {
+        if (seen.has(n.id))
+            return;
+        seen.add(n.id);
+        out.push(n);
+        for (const c of children.get(n.id) ?? [])
+            visit(c);
+    };
+    for (const r of children.get(null) ?? [])
+        visit(r);
+    // A parent cycle has no null-parent entry point: emit the leftovers as roots so none is lost.
+    for (const n of [...norm].sort(byName)) {
+        if (!seen.has(n.id))
+            visit({ ...n, parentId: null });
+    }
+    return out;
+}
+const DELETED_ROLE = 'Deleted role';
+const DELETED_NODE = 'Deleted company';
+/** Quote a list of names for a message: ‘A’, ‘B’ and ‘C’. */
+function quoteNames(names) {
+    const q = names.map((n) => `‘${n}’`);
+    return q.length <= 1 ? (q[0] ?? '') : `${q.slice(0, -1).join(', ')} and ${q[q.length - 1]}`;
+}
+class ServiceAccountService {
+    accounts;
+    keys;
+    hasher;
+    audit;
+    resolveName;
+    heldRoles;
+    now;
+    constructor(accounts, keys, hasher, audit, resolveName, heldRoles, now = Date.now) {
+        this.accounts = accounts;
+        this.keys = keys;
+        this.hasher = hasher;
+        this.audit = audit;
+        this.resolveName = resolveName;
+        this.heldRoles = heldRoles;
+        this.now = now;
+    }
+    /**
+     * Rows → views, resolving role + company NAMES in two batched reads (no N+1). Labels follow the
+     * id order; an id that no longer resolves gets a fallback label, never the id (ADR-0012).
+     */
+    async toViews(rows) {
+        if (rows.length === 0)
+            return [];
+        const [roles, nodes] = await Promise.all([
+            this.accounts.rolesByIds(rows.flatMap((r) => r.roleIds)),
+            this.accounts.nodesByIds(rows.flatMap((r) => r.scopeSubtreeNodeIds)),
+        ]);
+        const roleName = new Map(roles.map((r) => [r.id, r.name]));
+        const nodeName = new Map(nodes.map((n) => [n.id, n.name]));
+        return Promise.all(rows.map(async (row) => ({
+            id: row.id,
+            label: row.label,
+            scopeSubtreeNodeIds: row.scopeSubtreeNodeIds,
+            scopeLabels: row.scopeSubtreeNodeIds.map((id) => nodeName.get(id) ?? DELETED_NODE),
+            roleIds: row.roleIds,
+            roleLabels: row.roleIds.map((id) => roleName.get(id) ?? DELETED_ROLE),
+            status: row.status,
+            createdByName: row.createdBy ? await this.resolveName(row.createdBy) : null,
+            createdAtMs: row.createdAtMs,
+            updatedAtMs: row.updatedAtMs,
+        })));
+    }
+    /**
+     * The caller's ceiling with roles resolved LIVE ({@link HeldRoleResolver}). Root needs no role
+     * read. A resolver failure propagates (→ 503): fail closed, never an empty-or-stale ceiling.
+     */
+    async ceilingFor(admin) {
+        if (admin.isRoot === true)
+            return ceilingOf(admin, []);
+        return ceilingOf(admin, await this.heldRoles(admin.id, admin.tenantId));
+    }
+    /**
+     * Enforce the ADR-0029 ceiling ({@link ceilingOf}): every requested node must be within the
+     * ceiling's subtree and every requested role one the admin holds. Root bypasses. On violation
+     * throws a 403 — never with an id (ADR-0012), and NAMING an offender only when it is already on
+     * the agent being edited (`onAgent`, whose labels the caller sees anyway). Any other offender is
+     * described generically: the role/company catalog reads are not caller-scoped, so resolving a
+     * name for an arbitrary id would turn the 403 into a cross-tenant name/existence oracle.
+     */
+    async assertWithinCeiling(ceiling, scopeSubtreeNodeIds, roleIds, onAgent = {
+        nodes: [],
+        roles: [],
+    }) {
+        if (ceiling.isRoot)
+            return;
+        const badNodes = uniqueIds(scopeSubtreeNodeIds).filter((n) => !ceilingAllowsNode(ceiling, n));
+        if (badNodes.length > 0) {
+            const what = await this.describeOffenders(badNodes, onAgent.nodes, (ids) => this.accounts.nodesByIds(ids), 'company', 'companies');
+            throw new ServiceAccountCeilingError(`You can't give this agent access to ${what} — outside the companies you can reach.`);
+        }
+        const badRoles = uniqueIds(roleIds).filter((r) => !ceilingAllowsRole(ceiling, r));
+        if (badRoles.length > 0) {
+            const what = await this.describeOffenders(badRoles, onAgent.roles, (ids) => this.accounts.rolesByIds(ids), 'role', 'roles');
+            throw new ServiceAccountCeilingError(`You can't give this agent ${what} — you don't hold ${badRoles.length === 1 ? 'it' : 'them'}.`);
+        }
+    }
+    /**
+     * "the role ‘A’", "‘A’ and 2 other roles", "a role" … — names only offenders already on the agent.
+     */
+    async describeOffenders(bad, onAgent, lookup, noun, plural) {
+        const known = new Set(onAgent);
+        const nameable = bad.filter((id) => known.has(id));
+        const found = nameable.length > 0
+            ? new Map((await lookup(nameable)).map((x) => [x.id, x.name]))
+            : new Map();
+        const names = uniqueIds(nameable.map((id) => found.get(id) ?? '').filter((n) => n.length > 0));
+        const rest = bad.length - names.length;
+        if (names.length === 0)
+            return rest === 1 ? `a ${noun}` : `${rest} ${plural}`;
+        const named = `the ${names.length === 1 ? noun : plural} ${quoteNames(names)}`;
+        return rest === 0
+            ? named
+            : `${named} and ${rest === 1 ? `1 other ${noun}` : `${rest} other ${plural}`}`;
+    }
+    /**
+     * Resolve names for audit (ids already authorised for this caller: within ceiling, or on the
+     * agent). Best-effort like the audit itself: it runs AFTER the write, so a lookup failure falls
+     * back to placeholder names instead of failing a write that already happened.
+     */
+    async auditNames(roleIds, nodeIds) {
+        let roles = [];
+        let nodes = [];
+        try {
+            [roles, nodes] = await Promise.all([
+                roleIds.length ? this.accounts.rolesByIds(roleIds) : Promise.resolve([]),
+                nodeIds.length ? this.accounts.nodesByIds(nodeIds) : Promise.resolve([]),
+            ]);
+        }
+        catch {
+            // fall through with no names → DELETED_* placeholders
+        }
+        const roleName = new Map(roles.map((r) => [r.id, r.name]));
+        const nodeName = new Map(nodes.map((n) => [n.id, n.name]));
+        return {
+            roles: (ids) => ids.map((id) => roleName.get(id) ?? DELETED_ROLE),
+            nodes: (ids) => ids.map((id) => nodeName.get(id) ?? DELETED_NODE),
+        };
+    }
+    /**
+     * What the caller may grant (the picker source for create/edit), computed from the SAME
+     * {@link ceilingOf} the write check enforces. Root → every role + every company; non-root → the
+     * roles they hold + the nodes of their reachable subtree. Nodes come back tree-ordered with a
+     * `parentId` only when the parent is also assignable.
+     */
+    async assignable(admin) {
+        const ceiling = await this.ceilingFor(admin);
+        const [roles, nodes] = ceiling.isRoot
+            ? await Promise.all([this.accounts.allRoles(), this.accounts.allNodes()])
+            : await Promise.all([
+                this.accounts.rolesByIds([...ceiling.roleIds]),
+                this.accounts.nodesByIds([...ceiling.nodeIds]),
+            ]);
+        return {
+            // Defensive re-filter through the same predicates (a store that over-returns can't widen it).
+            roles: roles
+                .filter((r) => ceilingAllowsRole(ceiling, r.id))
+                .map((r) => ({ id: r.id, name: r.name })),
+            scopeNodes: treeOrder(nodes.filter((n) => ceilingAllowsNode(ceiling, n.id))),
+        };
+    }
+    /** List the admin's own-tenant accounts (by label; ids are handles). */
+    async list(admin) {
+        const rows = await this.accounts.list(scopeOf(admin));
+        return this.toViews(rows);
+    }
+    /** Fetch one own-tenant account; cross-tenant/unknown → 404. */
+    async get(admin, id) {
+        const row = await this.accounts.getById(id, scopeOf(admin));
+        if (row === null)
+            throw new ServiceAccountNotFoundError();
+        const [view] = await this.toViews([row]);
+        return view;
+    }
+    /**
+     * Create an account. `tenantId` is the admin's (server-stamped) — an account is created in the
+     * admin's OWN tenant only (a non-root admin cannot pick another tenant). Scope defaults to the
+     * admin's whole subtree when omitted; whatever is requested must pass the ceiling.
+     */
+    async create(admin, input) {
+        const label = input.label?.trim();
+        if (!label)
+            throw new ServiceAccountInputError('a label is required');
+        // Default the scope to the admin's own subtree (least surprise; still least-privilege-bounded).
+        const requestedScope = uniqueIds(input.scopeSubtreeNodeIds ?? []);
+        const scopeSubtree = requestedScope.length > 0
+            ? requestedScope
+            : admin.scopeSubtreeNodeIds.length
+                ? uniqueIds(admin.scopeSubtreeNodeIds)
+                : [admin.tenantId];
+        const roleIds = uniqueIds(input.roleIds ?? []);
+        await this.assertWithinCeiling(await this.ceilingFor(admin), scopeSubtree, roleIds);
+        const id = (0, node_crypto_1.randomUUID)();
+        const createdAtMs = this.now();
+        await this.accounts.insert({
+            id,
+            tenantId: admin.tenantId, // SERVER-STAMPED — never client input
+            label,
+            scopeSubtreeNodeIds: scopeSubtree,
+            roleIds,
+            status: 'active',
+            createdBy: admin.id,
+            createdAtMs,
+        });
+        const names = await this.auditNames(roleIds, scopeSubtree);
+        await this.safeAudit('service_account.created', admin, createdAtMs, {
+            accountId: id,
+            label,
+            scopeNodeCount: scopeSubtree.length,
+            roleCount: roleIds.length,
+            // WHAT was granted, by name (human-readable audit; names are not secrets).
+            roles: names.roles(roleIds),
+            scope: names.nodes(scopeSubtree),
+        });
+        return this.get(admin, id);
+    }
+    /**
+     * Edit an account's label/scope/roles/status (own-tenant; ceiling re-checked).
+     *
+     * Scope/roles semantics (Phase 4, confirmed 2026-10-08):
+     *  - `scopeSubtreeNodeIds: []` → 400 (an agent needs at least one scope node).
+     *  - What is REQUESTED must be ⊆ the editor's ceiling, else 403 — whatever the request shape
+     *    (duplicates, mixed lists, or re-sending an item the agent already has but the editor can't
+     *    grant). Nothing is written on a 403.
+     *  - NON-ROOT: the agent's EXISTING items outside the editor's ceiling are PRESERVED —
+     *    stored = requested ∪ (existing \ ceiling). A lower-ceiling admin can't strip access they could
+     *    never grant back; the preserved items come from the stored row, never the request, so the
+     *    merge can't add anything new. ROOT replaces with exactly what it sends.
+     */
+    async update(admin, id, patch) {
+        const hasField = patch.label !== undefined ||
+            patch.scopeSubtreeNodeIds !== undefined ||
+            patch.roleIds !== undefined ||
+            patch.status !== undefined;
+        if (!hasField)
+            throw new ServiceAccountInputError('no fields to update');
+        if (patch.label !== undefined && !patch.label.trim()) {
+            throw new ServiceAccountInputError('label cannot be empty');
+        }
+        if (patch.status !== undefined && patch.status !== 'active' && patch.status !== 'disabled') {
+            throw new ServiceAccountInputError("status must be 'active' or 'disabled'");
+        }
+        const requestedScope = patch.scopeSubtreeNodeIds !== undefined ? uniqueIds(patch.scopeSubtreeNodeIds) : undefined;
+        const requestedRoles = patch.roleIds !== undefined ? uniqueIds(patch.roleIds) : undefined;
+        if (requestedScope !== undefined && requestedScope.length === 0) {
+            throw new ServiceAccountInputError('choose at least one scope node');
+        }
+        // Own-tenant existence first (cross-tenant/unknown → 404, before any ceiling message).
+        const existing = await this.accounts.getById(id, scopeOf(admin));
+        if (existing === null)
+            throw new ServiceAccountNotFoundError();
+        // Re-check the ceiling for whatever is REQUESTED (an edit can't escalate either).
+        const ceiling = await this.ceilingFor(admin);
+        await this.assertWithinCeiling(ceiling, requestedScope ?? [], requestedRoles ?? [], {
+            nodes: existing.scopeSubtreeNodeIds,
+            roles: existing.roleIds,
+        });
+        // Preserve-merge (non-root only): keep the agent's existing out-of-ceiling items. Source is the
+        // STORED row, so nothing the editor sent can reach this branch.
+        const preservedScope = requestedScope !== undefined && !ceiling.isRoot
+            ? existing.scopeSubtreeNodeIds.filter((n) => !ceilingAllowsNode(ceiling, n))
+            : [];
+        const preservedRoles = requestedRoles !== undefined && !ceiling.isRoot
+            ? existing.roleIds.filter((r) => !ceilingAllowsRole(ceiling, r))
+            : [];
+        // Strictly after the row's last edit, so two edits in the same millisecond still differ and the
+        // optimistic guard below can tell them apart.
+        const updatedAtMs = Math.max(this.now(), (existing.updatedAtMs ?? 0) + 1);
+        const normalized = {
+            ...(patch.label !== undefined ? { label: patch.label.trim() } : {}),
+            ...(requestedScope !== undefined
+                ? { scopeSubtreeNodeIds: mergeIds(requestedScope, preservedScope) }
+                : {}),
+            ...(requestedRoles !== undefined
+                ? { roleIds: mergeIds(requestedRoles, preservedRoles) }
+                : {}),
+            ...(patch.status !== undefined ? { status: patch.status } : {}),
+        };
+        // The preserve-merge is a read-modify-write: guard it so a concurrent edit (e.g. root revoking an
+        // out-of-ceiling role) can't be undone by re-writing the stale `existing` set.
+        const merging = !ceiling.isRoot && (requestedScope !== undefined || requestedRoles !== undefined);
+        const changed = merging
+            ? await this.accounts.update(id, scopeOf(admin), normalized, updatedAtMs, existing.updatedAtMs)
+            : await this.accounts.update(id, scopeOf(admin), normalized, updatedAtMs);
+        if (changed === 0) {
+            if (merging && (await this.accounts.getById(id, scopeOf(admin))) !== null) {
+                throw new ServiceAccountConflictError();
+            }
+            throw new ServiceAccountNotFoundError();
+        }
+        // WHAT changed, by name: diff the stored sets (added ⊆ ceiling or root; removed were on the agent).
+        const diff = (before, after) => after === undefined
+            ? { added: [], removed: [] }
+            : {
+                added: after.filter((x) => !before.includes(x)),
+                removed: before.filter((x) => !after.includes(x)),
+            };
+        const roleDiff = diff(existing.roleIds, normalized.roleIds);
+        const scopeDiff = diff(existing.scopeSubtreeNodeIds, normalized.scopeSubtreeNodeIds);
+        const names = await this.auditNames([...roleDiff.added, ...roleDiff.removed], [...scopeDiff.added, ...scopeDiff.removed]);
+        await this.safeAudit('service_account.updated', admin, updatedAtMs, {
+            accountId: id,
+            fields: Object.keys(normalized),
+            ...(roleDiff.added.length > 0 ? { rolesAdded: names.roles(roleDiff.added) } : {}),
+            ...(roleDiff.removed.length > 0 ? { rolesRemoved: names.roles(roleDiff.removed) } : {}),
+            ...(scopeDiff.added.length > 0 ? { scopeAdded: names.nodes(scopeDiff.added) } : {}),
+            ...(scopeDiff.removed.length > 0 ? { scopeRemoved: names.nodes(scopeDiff.removed) } : {}),
+            ...(patch.status !== undefined ? { status: patch.status } : {}),
+            ...(preservedScope.length > 0 ? { preservedScopeNodeCount: preservedScope.length } : {}),
+            ...(preservedRoles.length > 0 ? { preservedRoleCount: preservedRoles.length } : {}),
+        });
+        return this.get(admin, id);
+    }
+    /**
+     * Issue a NEW key for an account (own-tenant). Mints `ask_<id>_<secret>`, hashes the secret, and
+     * persists the hash as the next version — carrying the ACCOUNT's current scope/roles onto the key
+     * (so the key's Principal reflects the account as it stands). Returns the raw key ONCE.
+     * ADR-0033 §4 (security hardening): the caller must give a FUTURE `expiresAtMs`, or opt in to a
+     * non-expiring key explicitly with `neverExpires: true` — otherwise 400, nothing minted.
+     */
+    async issueKey(admin, id, opts = {}) {
+        const expiresAtMs = this.resolveExpiry(opts);
+        const account = await this.accounts.getById(id, scopeOf(admin));
+        if (account === null)
+            throw new ServiceAccountNotFoundError();
+        return this.mintFor(account, admin, 'service_account.key_issued', expiresAtMs);
+    }
+    /**
+     * The key's expiry from the request: a future epoch-ms, or `undefined` when the caller said
+     * `neverExpires: true`. Neither, both, or a past/invalid time → ServiceAccountInputError (400).
+     */
+    resolveExpiry(opts) {
+        const hasExpiry = opts.expiresAtMs !== undefined;
+        if (hasExpiry && opts.neverExpires === true) {
+            throw new ServiceAccountInputError('Give either an expiry or neverExpires: true, not both.');
+        }
+        if (opts.neverExpires === true)
+            return undefined;
+        if (!hasExpiry) {
+            throw new ServiceAccountInputError('Choose when the key expires (expiresAtMs), or set neverExpires: true for a key that never expires.');
+        }
+        const ms = opts.expiresAtMs;
+        if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= this.now()) {
+            throw new ServiceAccountInputError('expiresAtMs must be a time in the future (epoch-ms).');
+        }
+        return ms;
+    }
+    /**
+     * Rotate an account's key: mint a new version (the old version stops being the current one —
+     * `getByAccountId` returns the highest, so the previous key no longer authenticates). Returns the
+     * new raw key ONCE.
+     */
+    async rotateKey(admin, id, opts = {}) {
+        const expiresAtMs = this.resolveExpiry(opts);
+        const account = await this.accounts.getById(id, scopeOf(admin));
+        if (account === null)
+            throw new ServiceAccountNotFoundError();
+        return this.mintFor(account, admin, 'service_account.key_rotated', expiresAtMs);
+    }
+    /** Revoke ALL of an account's keys (own-tenant) — fail-closed on the next request. Idempotent. */
+    async revokeKeys(admin, id) {
+        const account = await this.accounts.getById(id, scopeOf(admin));
+        if (account === null)
+            throw new ServiceAccountNotFoundError();
+        const atMs = this.now();
+        await this.keys.revoke(id, atMs);
+        await this.safeAudit('service_account.key_revoked', admin, atMs, { accountId: id });
+    }
+    /** Shared mint path for issue + rotate: version bump, hash, putVersion, audit, one-time reveal. */
+    async mintFor(account, admin, auditAction, expiresAtMs) {
+        const secret = mintSecret();
+        const version = (await this.keys.currentVersion(account.id)) + 1;
+        const secretHash = await this.hasher.hash(secret);
+        const createdAtMs = this.now();
+        await this.keys.putVersion({
+            accountId: account.id,
+            tenantId: account.tenantId,
+            scopeSubtreeNodeIds: account.scopeSubtreeNodeIds,
+            roleIds: account.roleIds,
+            secretHash,
+            version,
+            ...(expiresAtMs !== undefined ? { expiresAtMs } : {}),
+            createdAtMs,
+        });
+        await this.safeAudit(auditAction, admin, createdAtMs, {
+            accountId: account.id,
+            version,
+            expiresAtMs: expiresAtMs ?? null,
+        });
+        return {
+            apiKey: `${core_1.API_KEY_PREFIX}${account.id}_${secret}`,
+            accountLabel: account.label,
+            version,
+            expiresAtMs: expiresAtMs ?? null,
+        };
+    }
+    /** Best-effort audit — a sink throw must never fail a legitimate operation. */
+    async safeAudit(action, admin, occurredAtMs, attributes) {
+        try {
+            await this.audit.record({
+                action,
+                actorId: admin.id,
+                tenantId: admin.tenantId,
+                occurredAtMs,
+                attributes,
+            });
+        }
+        catch {
+            // swallow — auditing is best-effort here (the durable sink already logs its own failures).
+        }
+    }
+}
+exports.ServiceAccountService = ServiceAccountService;

package/dist/features/service-account/service-account.store.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ServiceAccountStore — the account-row CRUD for `shield_app.service_account` (ADR-0033). Separate
+ * from the guard's `MariaDbApiKeyStore` (which owns the HASHED KEYS in `shield_authz`): this store
+ * owns the ACCOUNT (label, scope, roles, status), the guard store owns its credentials.
+ *
+ * OWN-TENANT WALL: every read/update is scoped to the caller's subtree — a `SubtreeScope` splices a
+ * `sa_tenant_id IN (?, …)` predicate (mirroring `grant-admin.service.ts`). A root scope drops the
+ * predicate (spans all). A non-root with an empty subtree matches nothing (fail-closed, never a
+ * leak). A cross-tenant id therefore returns null → the service maps it to 404 (no existence leak).
+ *
+ * Every query is parameterized (node ids `?`-bound, never interpolated → injection-free). Server-
+ * stamped `sa_tenant_id` (from the session) on create — never client input.
+ */
+import type { Pool } from 'mariadb';
+/** The caller's reachable subtree (threaded from `req.principal`) — same shape as grant-admin. */
+export interface SubtreeScope {
+    readonly nodeIds: readonly string[];
+    readonly isRoot: boolean;
+}
+/** A persisted service account (raw row → view; JSON columns parsed). Ids are handles, not shown. */
+export interface ServiceAccountRow {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly label: string;
+    readonly scopeSubtreeNodeIds: readonly string[];
+    readonly roleIds: readonly string[];
+    readonly status: string;
+    readonly createdBy: string | null;
+    readonly createdAtMs: number;
+    readonly updatedAtMs: number | null;
+}
+/** A role as the picker / view needs it: handle + display name (ADR-0012 — the name is shown). */
+export interface RoleOption {
+    readonly id: string;
+    readonly name: string;
+}
+/** A scope node (company) as the picker needs it: handle + name + parent handle (for indent). */
+export interface ScopeNodeOption {
+    readonly id: string;
+    readonly name: string;
+    readonly parentId: string | null;
+}
+export declare class ServiceAccountStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    /** Roles by id (unknown ids are simply absent — the caller supplies a fallback label). */
+    rolesByIds(ids: readonly string[]): Promise<RoleOption[]>;
+    /** Every role in the catalog (ROOT's assignable set). */
+    allRoles(): Promise<RoleOption[]>;
+    /** Companies (scope nodes) by id, with their parent handle. Unknown ids are absent. */
+    nodesByIds(ids: readonly string[]): Promise<ScopeNodeOption[]>;
+    /** Every company (ROOT's assignable scope — root reaches all). */
+    allNodes(): Promise<ScopeNodeOption[]>;
+    /** List the caller's own-tenant accounts (newest first). Root sees all. */
+    list(scope: SubtreeScope): Promise<ServiceAccountRow[]>;
+    /** Fetch one account BY id, scoped to the caller's subtree. Cross-tenant/unknown → null (404). */
+    getById(id: string, scope: SubtreeScope): Promise<ServiceAccountRow | null>;
+    /**
+     * Insert a new account. `tenantId` is server-stamped (from the session) — never client input.
+     * `scopeSubtreeNodeIds`/`roleIds` are stored as JSON. Idempotency is the caller's (a fresh uuid
+     * per create); the id is unique by construction.
+     */
+    insert(input: {
+        id: string;
+        tenantId: string;
+        label: string;
+        scopeSubtreeNodeIds: readonly string[];
+        roleIds: readonly string[];
+        status: string;
+        createdBy: string;
+        createdAtMs: number;
+    }): Promise<void>;
+    /**
+     * Update an account's mutable fields (label/scope/roles/status), scoped to the caller's subtree.
+     * Returns the number of rows changed — 0 means the id was not in the caller's subtree (→ 404).
+     * Only the provided fields are set; `sa_updated_at_ms` is always stamped.
+     */
+    update(id: string, scope: SubtreeScope, patch: {
+        label?: string;
+        scopeSubtreeNodeIds?: readonly string[];
+        roleIds?: readonly string[];
+        status?: string;
+    }, updatedAtMs: number, 
+    /**
+     * Optimistic guard: when given, the row is only written if `sa_updated_at_ms` still equals this
+     * value (NULL-safe). A concurrent edit makes it return 0, so a read-modify-write can't resurrect
+     * access another admin just removed.
+     */
+    expectedUpdatedAtMs?: number | null): Promise<number>;
+}
+//# sourceMappingURL=service-account.store.d.ts.map

package/dist/features/service-account/service-account.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-account.store.d.ts","sourceRoot":"","sources":["../../../src/features/service-account/service-account.store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAIpC,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,qGAAqG;AACrG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AA2DD,kGAAkG;AAClG,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,iGAAiG;AACjG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAOD,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAMvC,0FAA0F;IACpF,UAAU,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAU/D,yDAAyD;IACnD,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAQvC,uFAAuF;IACjF,UAAU,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAUpE,kEAAkE;IAC5D,QAAQ,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAQ5C,2EAA2E;IACrE,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAS7D,kGAAkG;IAC5F,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IASjF;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;QACvC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjB;;;;OAIG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,EACD,WAAW,EAAE,MAAM;IACnB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAClC,OAAO,CAAC,MAAM,CAAC;CAgCnB"}