@astram/identity 0.20.0 → 0.22.0

package/dist/features/permission-announcement/permission-announcement.controller.js

@@ -0,0 +1,130 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionAnnouncementController = void 0;
+exports.parseAnnouncementQuery = parseAnnouncementQuery;
+exports.parsePermissionKeyParam = parsePermissionKeyParam;
+/**
+ * Permission announcements (G-027 step 4, spec `docs/features/permission-announcements/SPEC.md`
+ * v1 §3, §5.B): the caller's admin tasks for new, unassigned permission keys.
+ *
+ * Gated `identity:role:update`, the grant routes' own gate: only principals who could open the
+ * grant dialog reach these routes; the service then narrows to the caller's company and ceiling.
+ * Every path segment is validated here (400) and authorized in the service (404), never trusted.
+ */
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const identity_error_interceptor_js_1 = require("../shared/identity-error.interceptor.js");
+const permission_announcement_service_js_1 = require("./permission-announcement.service.js");
+/** An exact permission key `feature:object:action`, segments `^[a-z][a-z0-9_]*$`. */
+const PERMISSION_KEY = /^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$/;
+/** `role_permission.rp_perm_key` / `pad_perm_key` width. */
+const PERMISSION_KEY_MAX = 191;
+/** A positive whole number in decimal digits, or 400 naming the field (never the value). */
+function positiveInt(value, field, fallback, max) {
+    if (value === undefined || value === '')
+        return fallback;
+    if (typeof value !== 'string' || !/^[0-9]{1,9}$/.test(value)) {
+        throw new common_1.BadRequestException(`${field} must be a whole number`);
+    }
+    const n = Number.parseInt(value, 10);
+    if (n < 1 || (max !== undefined && n > max)) {
+        throw new common_1.BadRequestException(max === undefined ? `${field} must be at least 1` : `${field} must be between 1 and ${max}`);
+    }
+    return n;
+}
+/** Validate the list query (spec §3, §13: bad `status`/`page`/`limit`/uuid ⇒ 400). */
+function parseAnnouncementQuery(query) {
+    const q = query ?? {};
+    const rawStatus = q['status'];
+    let status = 'open';
+    if (rawStatus !== undefined && rawStatus !== '') {
+        if (typeof rawStatus !== 'string' ||
+            !permission_announcement_service_js_1.ANNOUNCEMENT_STATUSES.includes(rawStatus)) {
+            throw new common_1.BadRequestException(`status must be one of ${permission_announcement_service_js_1.ANNOUNCEMENT_STATUSES.join(', ')}`);
+        }
+        status = rawStatus;
+    }
+    const companyUuid = (0, guard_1.optionalUuidField)(q['companyUuid'], 'companyUuid');
+    return {
+        status,
+        page: positiveInt(q['page'], 'page', 1),
+        limit: positiveInt(q['limit'], 'limit', permission_announcement_service_js_1.ANNOUNCEMENT_DEFAULT_LIMIT, permission_announcement_service_js_1.ANNOUNCEMENT_MAX_LIMIT),
+        ...(companyUuid !== undefined ? { companyUuid } : {}),
+    };
+}
+/** Validate a `:key` route param (spec §5.B), or 400 (the value is never echoed). */
+function parsePermissionKeyParam(value) {
+    if (typeof value !== 'string' ||
+        value.length > PERMISSION_KEY_MAX ||
+        !PERMISSION_KEY.test(value)) {
+        throw new common_1.BadRequestException('key must be a permission key');
+    }
+    return value;
+}
+let PermissionAnnouncementController = class PermissionAnnouncementController {
+    announcements;
+    constructor(announcements) {
+        this.announcements = announcements;
+    }
+    /** The caller's tasks, grouped per company: `{ total, rows, page, limit }`. */
+    async list(req, query) {
+        return this.announcements.list(req.principal, parseAnnouncementQuery(query));
+    }
+    /** "Reviewed, not needed" (idempotent, audited). */
+    async dismiss(req, companyUuid, key) {
+        await this.announcements.dismiss(req.principal, companyUuid, parsePermissionKeyParam(key));
+    }
+    /** Undo a dismissal (idempotent, audited). */
+    async reopen(req, companyUuid, key) {
+        await this.announcements.reopen(req.principal, companyUuid, parsePermissionKeyParam(key));
+    }
+};
+exports.PermissionAnnouncementController = PermissionAnnouncementController;
+__decorate([
+    (0, common_1.Get)('permission-announcements'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], PermissionAnnouncementController.prototype, "list", null);
+__decorate([
+    (0, common_1.Post)('permission-announcements/:companyUuid/:key/dismiss'),
+    (0, common_1.HttpCode)(204),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('companyUuid', guard_1.UuidPipe)),
+    __param(2, (0, common_1.Param)('key')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, String]),
+    __metadata("design:returntype", Promise)
+], PermissionAnnouncementController.prototype, "dismiss", null);
+__decorate([
+    (0, common_1.Post)('permission-announcements/:companyUuid/:key/reopen'),
+    (0, common_1.HttpCode)(204),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('companyUuid', guard_1.UuidPipe)),
+    __param(2, (0, common_1.Param)('key')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, String]),
+    __metadata("design:returntype", Promise)
+], PermissionAnnouncementController.prototype, "reopen", null);
+exports.PermissionAnnouncementController = PermissionAnnouncementController = __decorate([
+    (0, common_1.Controller)('identity'),
+    (0, common_1.UseInterceptors)(identity_error_interceptor_js_1.IdentityErrorInterceptor),
+    __metadata("design:paramtypes", [permission_announcement_service_js_1.PermissionAnnouncementService])
+], PermissionAnnouncementController);

package/dist/features/permission-announcement/permission-announcement.service.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Permission announcements, step 4 of G-027 (spec `docs/features/permission-announcements/SPEC.md`
+ * v1, §5.A): one admin task per (company, new permission key) that no role owned by the company
+ * holds yet, shown only to administrators whose grant ceiling covers the key.
+ *
+ * Open tasks are computed on read (catalog ⋈ the company's roles); only "Reviewed, not needed"
+ * dismissals are stored (`<identity>.permission_announcement_dismissal`). A dismissal applies only
+ * while its `pad_activated_at` equals the key's current activation (`perm_last_activated_at`), so a
+ * key removed and re-added by a later release opens again.
+ *
+ * Tasks inform only: nothing here grants, changes the ceiling, bumps a version or touches
+ * `decide()` (Shield #3). Admin path only, never the request hot path (Shield #12).
+ *
+ * TIMESTAMPs never cross the driver as a JS `Date` (the authz pool sets no driver `timezone`):
+ * activations are copied and compared inside SQL, times are read with `UNIX_TIMESTAMP(col)`
+ * (`isoFromEpochSeconds`) and written with `CURRENT_TIMESTAMP(3)`.
+ */
+import type { Pool } from 'mariadb';
+import type { FrameworkSchemas, ModuleRegistry, Principal } from '@astram/core';
+import { type AuditPort } from '@astram/engine';
+import { type GrantCeiling } from '../authz/grant-ceiling.js';
+/** The resolved framework names this service needs (the dismissal table lives in `identity`). */
+export type AnnouncementSchemaNames = Pick<FrameworkSchemas, 'app' | 'authz' | 'identity'>;
+/** Task status (spec §10). */
+export declare const ANNOUNCEMENT_STATUSES: readonly ["open", "dismissed"];
+export type AnnouncementStatus = (typeof ANNOUNCEMENT_STATUSES)[number];
+/** Audit actions (spec §10). */
+export type AnnouncementAuditAction = 'permission_announcement.dismissed' | 'permission_announcement.reopened';
+/** Paging bounds (spec §3). */
+export declare const ANNOUNCEMENT_DEFAULT_LIMIT = 20;
+export declare const ANNOUNCEMENT_MAX_LIMIT = 100;
+/** One task row (spec §3). `companyUuid` is the task's own address for dismiss/reopen. */
+export interface PermissionAnnouncementRow {
+    companyUuid: string;
+    companyName: string;
+    key: string;
+    label: string;
+    description: string | null;
+    caution: string | null;
+    firstSeenAt: string | null;
+    firstSeenVersion: string | null;
+    status: AnnouncementStatus;
+    dismissedAt?: string | null;
+    dismissedByName?: string;
+}
+export interface PermissionAnnouncementQuery {
+    companyUuid?: string | undefined;
+    status: AnnouncementStatus;
+    page: number;
+    limit: number;
+}
+export interface PermissionAnnouncementPage {
+    total: number;
+    rows: PermissionAnnouncementRow[];
+    page: number;
+    limit: number;
+}
+/** The pool surface used: direct reads plus one connection per write transaction. */
+export type AnnouncementPool = Pick<Pool, 'query' | 'getConnection'>;
+export declare class PermissionAnnouncementService {
+    private readonly pool;
+    private readonly ceiling;
+    private readonly registry;
+    private readonly audit;
+    private readonly schemas;
+    /**
+     * @param pool     The ONE shared authz pool (reaches `<app>`, `<authz>`, `<identity>`, `<audit>`).
+     * @param ceiling  The ADR-0029 grant ceiling: a non-root caller sees only keys it could grant.
+     * @param registry The shared record-authorization registry (wildcard expansion universe, labels).
+     * @param audit    Written on the dismissal's own transaction (fail closed, Shield #6).
+     * @param schemas  Resolved framework names (absent ⇒ resolved from the namespace, once, here).
+     */
+    constructor(pool: AnnouncementPool, ceiling: Pick<GrantCeiling, 'effectiveKeys'>, registry: ModuleRegistry, audit: AuditPort, schemas?: AnnouncementSchemaNames);
+    /** The caller's actionable tasks (spec §5.A `list`). */
+    list(actor: Principal, query: PermissionAnnouncementQuery): Promise<PermissionAnnouncementPage>;
+    /**
+     * "Reviewed, not needed" (spec §5.A `dismiss`). Idempotent: already dismissed for the key's
+     * current activation ⇒ no write, no audit. Held in the company ⇒ 409.
+     */
+    dismiss(actor: Principal, companyUuid: string, key: string): Promise<void>;
+    /**
+     * Undo a dismissal (spec §5.A `reopen`). Idempotent: no dismissal for the key's current
+     * activation ⇒ no write, no audit. A stale row (earlier activation) is not a dismissal and is
+     * left as is (the read ignores it).
+     */
+    reopen(actor: Principal, companyUuid: string, key: string): Promise<void>;
+    /**
+     * The same authorization as `list` for one (company, key): company reachable (404), key a
+     * candidate (404) inside the caller's ceiling (404), and not held in the company (409; the task
+     * does not exist, so there is nothing to dismiss or reopen).
+     */
+    private authorizeTask;
+    /**
+     * The companies the caller acts in (spec §5.A step 1). Non-root: only the active tenant (a
+     * different `companyUuid` ⇒ 404, never trusted). Root: every company, or the one given (unknown
+     * ⇒ 404). `all` is true only for root without a filter (the held/dismissal reads then skip IN).
+     */
+    private companiesFor;
+    /**
+     * Candidate keys (spec §5.A step 2: active, first seen set) inside the caller's ceiling (step 3:
+     * non-root keeps `coversKey(effectiveKeys(actor), registered, key)`; root keeps all). `onlyKey`
+     * narrows the read to one key (dismiss/reopen).
+     */
+    private actionableCandidates;
+    /**
+     * Each company's held exact keys (spec §5.A step 4): one read of `role_permission` rows of the
+     * roles the companies own, raw keys (exact or wildcard) expanded per company with
+     * `expandGrantKeys`. The universe is the registry's keys plus the candidate keys, so an exact
+     * grant of a catalogued key always counts as held.
+     */
+    private heldKeys;
+    /**
+     * The dismissals that apply (spec §5.A step 5): a row whose `pad_activated_at` equals the key's
+     * current activation, compared in SQL. Any other row is stale and ignored. The dismisser is a
+     * name (user, else service account, else "Deleted user"), never the uuid.
+     */
+    private dismissals;
+    /**
+     * Lock the (company, key) dismissal row on `conn`, re-check that no company role holds the key
+     * under that lock (409; a grant may have landed since `authorizeTask`), then report whether the
+     * row is a dismissal for the key's current activation. Only the dismissal row is locked: the
+     * activation comparison is a plain read, so the catalog row the reconciler updates stays free.
+     */
+    private lockCurrentDismissal;
+    /**
+     * The audit row on the write's transaction (spec §5.A; Shield #6): `admin_action` under the
+     * task's company, names and the key label, never ids beyond the event's actor/tenant fields.
+     * An actor bound to a declared operation is attributed as in grant administration.
+     */
+    private auditChange;
+    /**
+     * One authz-pool transaction: `body` then commit; any failure rolls back. Identity errors pass
+     * through; every other failure (store, audit) is a 503 (`AuthorizationUnavailableError`).
+     */
+    private inTransaction;
+    /** Run reads, mapping any non-domain failure to `AuthorizationUnavailableError` (503). */
+    private store;
+    /** The registry's exact-key universe (as `GrantCeiling`). */
+    private registeredKeys;
+    /** The stored label, else the generated one (as the access-change notifier). */
+    private labelOf;
+}
+//# sourceMappingURL=permission-announcement.service.d.ts.map

package/dist/features/permission-announcement/permission-announcement.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-announcement.service.d.ts","sourceRoot":"","sources":["../../../src/features/permission-announcement/permission-announcement.service.ts"],"names":[],"mappings":"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"}

package/dist/features/permission-announcement/permission-announcement.service.js

@@ -0,0 +1,389 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionAnnouncementService = exports.ANNOUNCEMENT_MAX_LIMIT = exports.ANNOUNCEMENT_DEFAULT_LIMIT = exports.ANNOUNCEMENT_STATUSES = void 0;
+const core_1 = require("@astram/core");
+const engine_1 = require("@astram/engine");
+const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const db_permission_facts_adapter_js_1 = require("../authz/db-permission-facts.adapter.js");
+const mariadb_catalog_store_js_1 = require("../authz/mariadb-catalog-store.js");
+const access_change_notifier_js_1 = require("../authz/access-change-notifier.js");
+const http_js_1 = require("../shared/http.js");
+const identity_errors_js_1 = require("../shared/identity-errors.js");
+const schema_js_1 = require("../../schema.js");
+/** Task status (spec §10). */
+exports.ANNOUNCEMENT_STATUSES = ['open', 'dismissed'];
+/** Paging bounds (spec §3). */
+exports.ANNOUNCEMENT_DEFAULT_LIMIT = 20;
+exports.ANNOUNCEMENT_MAX_LIMIT = 100;
+/** Shown for a dismisser who no longer exists (never the uuid; data-safety rule). */
+const DELETED_ACTOR = 'Deleted user';
+/** The one 404 message for every unreachable task (no existence leak, no ids). */
+const TASK_NOT_FOUND = 'Permission announcement not found.';
+/** 409 for a key a company role already holds: the task does not exist, so nothing to review. */
+const heldConflict = () => new identity_errors_js_1.IdentityConflictError('A role in this organisation already holds this permission; there is nothing to review.');
+/**
+ * The key's activation as one SQL expression over `<authz>.permission p`. `perm_last_activated_at`
+ * is stamped with first seen by the reconciler's insert; the COALESCE only covers a hand-edited row
+ * where it is NULL (the dismissal column is NOT NULL), so that row can still be dismissed.
+ */
+const ACTIVATION = 'COALESCE(p.perm_last_activated_at, p.perm_first_seen_at)';
+/** Map a uuid to a case-insensitive map key (stored uuids may differ in case only). */
+const idKey = (uuid) => uuid.toLowerCase();
+/** Identity errors pass through a store failure mapping untouched. */
+function isDomainError(err) {
+    return (err instanceof identity_errors_js_1.IdentityNotFoundError ||
+        err instanceof identity_errors_js_1.IdentityConflictError ||
+        err instanceof identity_errors_js_1.IdentityBadRequestError ||
+        err instanceof identity_errors_js_1.IdentityForbiddenError);
+}
+class PermissionAnnouncementService {
+    pool;
+    ceiling;
+    registry;
+    audit;
+    schemas;
+    /**
+     * @param pool     The ONE shared authz pool (reaches `<app>`, `<authz>`, `<identity>`, `<audit>`).
+     * @param ceiling  The ADR-0029 grant ceiling: a non-root caller sees only keys it could grant.
+     * @param registry The shared record-authorization registry (wildcard expansion universe, labels).
+     * @param audit    Written on the dismissal's own transaction (fail closed, Shield #6).
+     * @param schemas  Resolved framework names (absent ⇒ resolved from the namespace, once, here).
+     */
+    constructor(pool, ceiling, registry, audit, schemas = (0, schema_js_1.frameworkSchemasFromEnv)()) {
+        this.pool = pool;
+        this.ceiling = ceiling;
+        this.registry = registry;
+        this.audit = audit;
+        this.schemas = schemas;
+    }
+    /** The caller's actionable tasks (spec §5.A `list`). */
+    async list(actor, query) {
+        return this.store('permission announcements', async () => {
+            const { companies, all } = await this.companiesFor(actor, query.companyUuid);
+            const candidates = await this.actionableCandidates(actor);
+            const rows = [];
+            if (companies.length > 0 && candidates.length > 0) {
+                const held = await this.heldKeys(companies, all, candidates.map((c) => c.key));
+                const dismissed = await this.dismissals(companies, all);
+                for (const company of companies) {
+                    const heldHere = held.get(idKey(company.uuid)) ?? new Set();
+                    for (const c of candidates) {
+                        if (heldHere.has(c.key))
+                            continue;
+                        const d = dismissed.get(`${idKey(company.uuid)}\u0000${c.key}`);
+                        const status = d ? 'dismissed' : 'open';
+                        if (status !== query.status)
+                            continue;
+                        rows.push({
+                            companyUuid: company.uuid,
+                            companyName: company.name,
+                            key: c.key,
+                            label: c.label,
+                            description: c.description,
+                            caution: c.caution,
+                            firstSeenAt: c.firstSeenAt,
+                            firstSeenVersion: c.firstSeenVersion,
+                            status,
+                            ...(d ? { dismissedAt: d.dismissedAt, dismissedByName: d.dismissedByName } : {}),
+                        });
+                    }
+                }
+            }
+            rows.sort(compareRows);
+            const start = (query.page - 1) * query.limit;
+            return {
+                total: rows.length,
+                rows: rows.slice(start, start + query.limit),
+                page: query.page,
+                limit: query.limit,
+            };
+        });
+    }
+    /**
+     * "Reviewed, not needed" (spec §5.A `dismiss`). Idempotent: already dismissed for the key's
+     * current activation ⇒ no write, no audit. Held in the company ⇒ 409.
+     */
+    async dismiss(actor, companyUuid, key) {
+        const task = await this.authorizeTask(actor, companyUuid, key);
+        await this.inTransaction('permission announcement dismiss', async (conn) => {
+            const current = await this.lockCurrentDismissal(conn, task);
+            if (current)
+                return; // same activation already dismissed: nothing to write or audit
+            const res = (await conn.query(`INSERT INTO \`${this.schemas.identity}\`.\`permission_announcement_dismissal\`
+           (pad_company_uuid, pad_perm_key, pad_activated_at, pad_dismissed_by, pad_dismissed_at)
+         SELECT ?, p.perm_key, ${ACTIVATION}, ?, CURRENT_TIMESTAMP(3)
+           FROM \`${this.schemas.authz}\`.\`permission\` p
+          WHERE p.perm_key = ? AND p.perm_status = 'active' AND p.perm_first_seen_at IS NOT NULL
+         ON DUPLICATE KEY UPDATE
+           pad_activated_at = VALUES(pad_activated_at),
+           pad_dismissed_by = VALUES(pad_dismissed_by),
+           pad_dismissed_at = VALUES(pad_dismissed_at)`, [task.company.uuid, actor.id, task.candidate.key]));
+            // The key left the catalog (orphaned) between the check and the write.
+            if (Number(res?.affectedRows ?? 0) === 0)
+                throw new identity_errors_js_1.IdentityNotFoundError(TASK_NOT_FOUND);
+            await this.auditChange(conn, 'permission_announcement.dismissed', actor, task);
+        });
+    }
+    /**
+     * Undo a dismissal (spec §5.A `reopen`). Idempotent: no dismissal for the key's current
+     * activation ⇒ no write, no audit. A stale row (earlier activation) is not a dismissal and is
+     * left as is (the read ignores it).
+     */
+    async reopen(actor, companyUuid, key) {
+        const task = await this.authorizeTask(actor, companyUuid, key);
+        await this.inTransaction('permission announcement reopen', async (conn) => {
+            const current = await this.lockCurrentDismissal(conn, task);
+            if (!current)
+                return;
+            await conn.query(`DELETE FROM \`${this.schemas.identity}\`.\`permission_announcement_dismissal\`
+          WHERE pad_company_uuid = ? AND pad_perm_key = ?`, [task.company.uuid, task.candidate.key]);
+            await this.auditChange(conn, 'permission_announcement.reopened', actor, task);
+        });
+    }
+    // ── Authorization ─────────────────────────────────────────────────────────────────────────
+    /**
+     * The same authorization as `list` for one (company, key): company reachable (404), key a
+     * candidate (404) inside the caller's ceiling (404), and not held in the company (409; the task
+     * does not exist, so there is nothing to dismiss or reopen).
+     */
+    async authorizeTask(actor, companyUuid, key) {
+        return this.store('permission announcement', async () => {
+            const { companies } = await this.companiesFor(actor, companyUuid);
+            const company = companies[0];
+            if (!company)
+                throw new identity_errors_js_1.IdentityNotFoundError(TASK_NOT_FOUND);
+            const candidate = (await this.actionableCandidates(actor, key))[0];
+            if (!candidate)
+                throw new identity_errors_js_1.IdentityNotFoundError(TASK_NOT_FOUND);
+            const held = await this.heldKeys([company], false, [candidate.key]);
+            if (held.get(idKey(company.uuid))?.has(candidate.key))
+                throw heldConflict();
+            return { company, candidate };
+        });
+    }
+    /**
+     * The companies the caller acts in (spec §5.A step 1). Non-root: only the active tenant (a
+     * different `companyUuid` ⇒ 404, never trusted). Root: every company, or the one given (unknown
+     * ⇒ 404). `all` is true only for root without a filter (the held/dismissal reads then skip IN).
+     */
+    async companiesFor(actor, companyUuid) {
+        const isRoot = actor.isRoot === true;
+        if (!isRoot && companyUuid !== undefined && !(0, http_js_1.sameUuid)(companyUuid, actor.tenantId)) {
+            throw new identity_errors_js_1.IdentityNotFoundError(TASK_NOT_FOUND);
+        }
+        const target = isRoot ? companyUuid : actor.tenantId;
+        if (target === undefined) {
+            const rows = (await this.pool.query(`SELECT c_uuid, c_name FROM \`${this.schemas.app}\`.\`companies\``));
+            return { companies: rows.map((r) => ({ uuid: r.c_uuid, name: r.c_name })), all: true };
+        }
+        const rows = (await this.pool.query(`SELECT c_uuid, c_name FROM \`${this.schemas.app}\`.\`companies\` WHERE c_uuid = ? LIMIT 1`, [target]));
+        const row = rows[0];
+        if (!row)
+            throw new identity_errors_js_1.IdentityNotFoundError(TASK_NOT_FOUND);
+        return { companies: [{ uuid: row.c_uuid, name: row.c_name }], all: false };
+    }
+    /**
+     * Candidate keys (spec §5.A step 2: active, first seen set) inside the caller's ceiling (step 3:
+     * non-root keeps `coversKey(effectiveKeys(actor), registered, key)`; root keeps all). `onlyKey`
+     * narrows the read to one key (dismiss/reopen).
+     */
+    async actionableCandidates(actor, onlyKey) {
+        const rows = (await this.pool.query(`SELECT perm_key, perm_label, perm_description, perm_caution,
+              UNIX_TIMESTAMP(perm_first_seen_at) AS perm_first_seen_at, perm_first_seen_version
+         FROM \`${this.schemas.authz}\`.\`permission\`
+        WHERE perm_status = 'active' AND perm_first_seen_at IS NOT NULL${onlyKey === undefined ? '' : ' AND perm_key = ?'}`, onlyKey === undefined ? [] : [onlyKey]));
+        // A collation-equal match is not the key asked for (case or pad differences): exact only.
+        const matching = onlyKey === undefined ? rows : rows.filter((r) => r.perm_key === onlyKey);
+        let kept = matching;
+        if (actor.isRoot !== true) {
+            if (matching.length === 0)
+                return [];
+            const effective = await this.ceiling.effectiveKeys(actor);
+            const registered = this.registeredKeys();
+            kept = matching.filter((r) => (0, grant_ceiling_js_1.coversKey)(effective, registered, r.perm_key));
+        }
+        return kept.map((r) => ({
+            key: r.perm_key,
+            label: this.labelOf(r.perm_key, r.perm_label),
+            description: r.perm_description ?? null,
+            caution: r.perm_caution ?? null,
+            firstSeenAt: (0, mariadb_catalog_store_js_1.isoFromEpochSeconds)(r.perm_first_seen_at),
+            firstSeenVersion: r.perm_first_seen_version ?? null,
+        }));
+    }
+    /**
+     * Each company's held exact keys (spec §5.A step 4): one read of `role_permission` rows of the
+     * roles the companies own, raw keys (exact or wildcard) expanded per company with
+     * `expandGrantKeys`. The universe is the registry's keys plus the candidate keys, so an exact
+     * grant of a catalogued key always counts as held.
+     */
+    async heldKeys(companies, all, candidateKeys, query = (sql, params) => this.pool.query(sql, params)) {
+        const ids = companies.map((c) => c.uuid);
+        const where = all
+            ? 'r.r_owner_company_uuid IS NOT NULL'
+            : `r.r_owner_company_uuid IN (${ids.map(() => '?').join(', ')})`;
+        const rows = (await query(`SELECT r.r_owner_company_uuid AS company, rp.rp_perm_key AS perm_key
+         FROM \`${this.schemas.app}\`.\`roles\` r
+         JOIN \`${this.schemas.authz}\`.\`role_permission\` rp ON rp.rp_role_uuid = r.r_uuid
+        WHERE ${where}`, all ? [] : ids));
+        const rawByCompany = new Map();
+        for (const r of rows) {
+            const k = idKey(r.company);
+            const list = rawByCompany.get(k);
+            if (list)
+                list.push(r.perm_key);
+            else
+                rawByCompany.set(k, [r.perm_key]);
+        }
+        const universe = [...new Set([...this.registeredKeys(), ...candidateKeys])];
+        const out = new Map();
+        for (const [company, raw] of rawByCompany) {
+            out.set(company, new Set((0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, universe)));
+        }
+        return out;
+    }
+    /**
+     * The dismissals that apply (spec §5.A step 5): a row whose `pad_activated_at` equals the key's
+     * current activation, compared in SQL. Any other row is stale and ignored. The dismisser is a
+     * name (user, else service account, else "Deleted user"), never the uuid.
+     */
+    async dismissals(companies, all) {
+        const ids = companies.map((c) => c.uuid);
+        const where = all ? '' : `WHERE d.pad_company_uuid IN (${ids.map(() => '?').join(', ')})`;
+        const rows = (await this.pool.query(`SELECT d.pad_company_uuid AS company, d.pad_perm_key AS perm_key,
+              UNIX_TIMESTAMP(d.pad_dismissed_at) AS dismissed_at,
+              COALESCE(u.u_username, sa.sa_label) AS dismissed_by_name
+         FROM \`${this.schemas.identity}\`.\`permission_announcement_dismissal\` d
+         JOIN \`${this.schemas.authz}\`.\`permission\` p
+           ON p.perm_key = d.pad_perm_key AND d.pad_activated_at = ${ACTIVATION}
+         LEFT JOIN \`${this.schemas.app}\`.\`users\` u ON u.u_uuid = d.pad_dismissed_by
+         LEFT JOIN \`${this.schemas.app}\`.\`service_account\` sa ON sa.sa_id = d.pad_dismissed_by
+        ${where}`, all ? [] : ids));
+        const out = new Map();
+        for (const r of rows) {
+            out.set(`${idKey(r.company)}\u0000${r.perm_key}`, {
+                dismissedAt: (0, mariadb_catalog_store_js_1.isoFromEpochSeconds)(r.dismissed_at),
+                dismissedByName: r.dismissed_by_name ?? DELETED_ACTOR,
+            });
+        }
+        return out;
+    }
+    // ── Writes ────────────────────────────────────────────────────────────────────────────────
+    /**
+     * Lock the (company, key) dismissal row on `conn`, re-check that no company role holds the key
+     * under that lock (409; a grant may have landed since `authorizeTask`), then report whether the
+     * row is a dismissal for the key's current activation. Only the dismissal row is locked: the
+     * activation comparison is a plain read, so the catalog row the reconciler updates stays free.
+     */
+    async lockCurrentDismissal(conn, task) {
+        const { company, candidate } = task;
+        await conn.query(`SELECT pad_perm_key
+         FROM \`${this.schemas.identity}\`.\`permission_announcement_dismissal\`
+        WHERE pad_company_uuid = ? AND pad_perm_key = ?
+        FOR UPDATE`, [company.uuid, candidate.key]);
+        const held = await this.heldKeys([company], false, [candidate.key], (sql, params) => conn.query(sql, params));
+        if (held.get(idKey(company.uuid))?.has(candidate.key))
+            throw heldConflict();
+        const rows = (await conn.query(`SELECT (d.pad_activated_at = ${ACTIVATION}) AS is_current
+         FROM \`${this.schemas.identity}\`.\`permission_announcement_dismissal\` d
+         LEFT JOIN \`${this.schemas.authz}\`.\`permission\` p ON p.perm_key = d.pad_perm_key
+        WHERE d.pad_company_uuid = ? AND d.pad_perm_key = ?`, [company.uuid, candidate.key]));
+        const v = rows[0]?.is_current;
+        return v !== undefined && v !== null && Number(v) === 1;
+    }
+    /**
+     * The audit row on the write's transaction (spec §5.A; Shield #6): `admin_action` under the
+     * task's company, names and the key label, never ids beyond the event's actor/tenant fields.
+     * An actor bound to a declared operation is attributed as in grant administration.
+     */
+    async auditChange(conn, action, actor, task) {
+        const op = (0, engine_1.operationOf)(actor);
+        const operationAttributes = !op
+            ? {}
+            : { operation: op.operationKey, step: op.stepKey, onBehalfOf: op.onBehalfOf };
+        await this.audit.record({
+            type: 'admin_action',
+            occurredAtMs: Date.now(),
+            actorId: actor.id,
+            tenantId: task.company.uuid,
+            action: { key: action },
+            attributes: {
+                eventType: 'permission_announcement',
+                key: task.candidate.key,
+                label: task.candidate.label,
+                company: task.company.name,
+                firstSeenVersion: task.candidate.firstSeenVersion,
+                ...operationAttributes,
+            },
+        }, (sql, params) => conn.query(sql, params));
+    }
+    /**
+     * One authz-pool transaction: `body` then commit; any failure rolls back. Identity errors pass
+     * through; every other failure (store, audit) is a 503 (`AuthorizationUnavailableError`).
+     */
+    async inTransaction(what, body) {
+        let conn;
+        try {
+            conn = (await this.pool.getConnection());
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError(`${what} failed`, cause);
+        }
+        try {
+            await conn.beginTransaction();
+            await body(conn);
+            await conn.commit();
+        }
+        catch (cause) {
+            try {
+                await conn.rollback();
+            }
+            catch {
+                // The connection is released below; the original failure is what the caller sees.
+            }
+            if (isDomainError(cause))
+                throw cause;
+            throw new core_1.AuthorizationUnavailableError(`${what} failed`, cause);
+        }
+        finally {
+            await conn.release();
+        }
+    }
+    // ── Helpers ───────────────────────────────────────────────────────────────────────────────
+    /** Run reads, mapping any non-domain failure to `AuthorizationUnavailableError` (503). */
+    async store(what, read) {
+        try {
+            return await read();
+        }
+        catch (cause) {
+            if (isDomainError(cause) || cause instanceof core_1.AuthorizationUnavailableError)
+                throw cause;
+            throw new core_1.AuthorizationUnavailableError(`${what} unavailable`, cause);
+        }
+    }
+    /** The registry's exact-key universe (as `GrantCeiling`). */
+    registeredKeys() {
+        return this.registry.listActions().map((a) => a.permissionKey);
+    }
+    /** The stored label, else the generated one (as the access-change notifier). */
+    labelOf(key, stored) {
+        return stored && stored !== key ? stored : (0, access_change_notifier_js_1.generatedPermissionLabel)(this.registry, key);
+    }
+}
+exports.PermissionAnnouncementService = PermissionAnnouncementService;
+/** Spec §5.A step 6: company name, then first seen (newest first, unknown last), then label. */
+function compareRows(a, b) {
+    const byCompany = a.companyName.localeCompare(b.companyName);
+    if (byCompany !== 0)
+        return byCompany;
+    if (a.companyUuid !== b.companyUuid)
+        return a.companyUuid < b.companyUuid ? -1 : 1;
+    const ta = a.firstSeenAt === null ? -Infinity : Date.parse(a.firstSeenAt);
+    const tb = b.firstSeenAt === null ? -Infinity : Date.parse(b.firstSeenAt);
+    if (ta !== tb)
+        return tb > ta ? 1 : -1;
+    const byLabel = a.label.localeCompare(b.label);
+    if (byLabel !== 0)
+        return byLabel;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+}