@astram/guard 0.2.0 → 0.4.0

package/dist/authz/cross-tenant-grant-writer.js

@@ -0,0 +1,397 @@
+"use strict";
+/**
+ * `CrossTenantGrantWriter` — the framework-owned WHO-MAY-GRANT write path (ADR-0009, the KEY
+ * NEW INVARIANT of Phase 4). Cross-tenant grant LIFECYCLE — offer / accept / revoke — is
+ * framework-governed here so a grant can NEVER be minted by the party that BENEFITS from it.
+ *
+ * ⛔ THIS IS NOT A CORE PORT. Grant EVALUATION is a core port ({@link CrossTenantGrantPort});
+ *    grant LIFECYCLE is a guard WRITE path (it needs the `mariadb` driver + the consumer's
+ *    identity schema to answer "is X an admin of tenant T", neither of which core may touch —
+ *    ADR-0003). It lives in guard and is exposed as a provider the consumer app's grant surface
+ *    calls (the invitation-email / inbox UX is DEFERRED — ADR-0009's Admin-Console follow-up).
+ *
+ * ── THE CONSENT MODEL (ADR-0009). A cross-tenant grant is TENANT B (the OWNING tenant, whose
+ *    data is reached into) consenting to let TENANT A's principal in. The handshake:
+ *      offer  → an owner/ADMIN in the OWNING tenant (or root) declares the grant
+ *               (object type, scope, action ceiling, expiry) → row created in 'offered' status.
+ *      accept → the GRANTEE tenant must ACCEPT → row moves to 'accepted' → the grant ACTIVATES
+ *               (only now does {@link CrossTenantGrantPort.findActiveGrant} return it).
+ *      revoke → EITHER side (owning tenant admin OR grantee tenant member) may revoke → row
+ *               moves to 'revoked' + `ctg_revoked_at` stamped → immediately inactive.
+ *    ⛔ THE #1 SECURITY CRUX: the grantee's OWN tenant can NEVER unilaterally mint a grant. A
+ *    grant is consent FROM the owning tenant; only an owning-tenant admin may OFFER.
+ *
+ * ── THE BOUNDS (enforced fail-closed, IN ORDER, BEFORE any write):
+ *   • offer:
+ *       1. The offerer MUST hold `'share'` authority in the OWNING tenant (`ctg_owning_tenant_uuid`)
+ *          — verified SERVER-SIDE via the injected {@link GrantAuthorizeFn} (the app's `decide()`);
+ *          rejected otherwise. ⛔ `offeredBy` + `owningTenantId` come from the AUTHENTICATED
+ *          principal context — the caller supplies them from the request principal, NEVER from
+ *          a user-controlled body field for the authority decision.
+ *       2. `allowedActions` MUST be non-empty AND MUST NOT contain a wildcard (`'*'`) — the
+ *          ceiling is a hard, explicit, enumerated set (ADR-0009: "non-wildcard, non-empty").
+ *       3. `expiresAtMs` MUST be a finite FUTURE timestamp — no perpetual / absent / past
+ *          expiry (ADR-0009: "expiry mandatory").
+ *       4. scope='record' REQUIRES a non-empty `recordId`; scope='object_type' FORBIDS one.
+ *     On pass ⇒ INSERT a fresh row in 'offered' status.
+ *   • accept:
+ *       Only a principal who holds `'accept'` authority in the GRANTEE tenant (`ctg_grantee_tenant_uuid`)
+ *       may accept — verified via {@link GrantAuthorizeFn} (the app's `decide()`, which implies
+ *       grantee-tenant membership); and only a grant
+ *       currently in 'offered' status (not already accepted/revoked). On pass ⇒ UPDATE to
+ *       'accepted' + stamp `ctg_accepted_at`. Re-accepting an already-'accepted' grant is a
+ *       benign no-op (idempotent). Accepting a 'revoked' grant is REJECTED (a revoked grant is
+ *       dead — it must be re-offered).
+ *   • revoke:
+ *       EITHER an admin of the OWNING tenant OR a member of the GRANTEE tenant may revoke
+ *       (ADR-0009: "either side may revoke immediately"). A stranger (neither) is REJECTED. On
+ *       pass ⇒ UPDATE to 'revoked' + stamp `ctg_revoked_at`. Re-revoking an already-'revoked'
+ *       grant is a benign no-op (idempotent).
+ *
+ * ── AUDIT ON BOTH TENANTS (ADR-0009: "audited on BOTH tenants as cross-tenant"). Every
+ *    offer/accept/revoke emits ONE {@link GrantAuditEvent} through the injected
+ *    {@link GrantAuditSink} carrying BOTH `owningTenantId` and `granteeTenantId` in STRUCTURED
+ *    fields — so the consumer's sink can record it under each tenant's audit trail. NO raw uuid
+ *    appears in any human-readable MESSAGE (ids ride in structured attributes only). Best-effort
+ *    — a sink throw never fails the lifecycle operation.
+ *
+ * ── FETCH-THEN-GATE (mirrors {@link RecordShareWriter}). The authority decisions (is-admin /
+ *    is-member) are resolved SERVER-SIDE via the injected resolver — NEVER trusted from caller
+ *    input. accept/revoke FETCH the grant's owning+grantee tenants from the row (not from the
+ *    caller) before deciding who may act.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossTenantGrantWriter = exports.GrantStoreUnavailableError = exports.InvalidGrantError = exports.GrantNotPermittedError = exports.SHIELD_CROSS_TENANT_GRANT_WRITER = void 0;
+const node_crypto_1 = require("node:crypto");
+/** Schema the `cross_tenant_grant` table lives in (astram3 ships the migration). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/** The DI token the writer is bound under. */
+exports.SHIELD_CROSS_TENANT_GRANT_WRITER = Symbol('SHIELD_CROSS_TENANT_GRANT_WRITER');
+/** Thrown when the who-may-grant bound rejects an offer/accept/revoke (fail-closed). */
+class GrantNotPermittedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GrantNotPermittedError';
+    }
+}
+exports.GrantNotPermittedError = GrantNotPermittedError;
+/** Thrown when the grant input is malformed (bad ceiling / expiry / scope). */
+class InvalidGrantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidGrantError';
+    }
+}
+exports.InvalidGrantError = InvalidGrantError;
+/** Thrown when the grant store genuinely cannot answer/write (transient → 503-retryable). */
+class GrantStoreUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GrantStoreUnavailableError';
+    }
+}
+exports.GrantStoreUnavailableError = GrantStoreUnavailableError;
+/**
+ * Parse a `ctg_allowed_actions` cell to a `string[]`, accepting BOTH an already-parsed array
+ * (production — the mariadb driver auto-parses the JSON column) and a JSON string (test mocks).
+ * Anything else / malformed ⇒ `[]` (fail-closed). Shared shape with the adapter's parser.
+ */
+function parseCeiling(raw) {
+    if (Array.isArray(raw)) {
+        return raw.filter((a) => typeof a === 'string');
+    }
+    if (typeof raw === 'string' && raw.length > 0) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return parsed.filter((a) => typeof a === 'string');
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+class CrossTenantGrantWriter {
+    db;
+    authorize;
+    audit;
+    schema;
+    now;
+    constructor(deps) {
+        this.db = deps.db;
+        this.authorize = deps.authorize;
+        this.audit = deps.audit;
+        this.schema = deps.schema ?? DEFAULT_SCHEMA;
+        this.now = deps.nowMs ?? (() => Date.now());
+    }
+    /**
+     * OFFER a grant — the OWNING tenant consents to let a grantee tenant's principal in. Enforces
+     * the offer bound (owning-tenant admin, non-empty/non-wildcard ceiling, future expiry, scope
+     * ↔ recordId). Creates a fresh row in 'offered' status. Emits `grant.offered`.
+     *
+     * @returns the new grant's uuid.
+     * @throws {@link GrantNotPermittedError} if the offerer is not an owning-tenant admin.
+     * @throws {@link InvalidGrantError} on a bad ceiling / expiry / scope.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async offer(input) {
+        // (2)–(4) input validity BEFORE any authority I/O (cheap, deterministic, fail-closed).
+        this.assertValidOffer(input);
+        // (1) THE CRUX: the offerer MUST be an admin of the OWNING tenant — resolved SERVER-SIDE
+        // (never trusted from input). The grantee's own tenant can never mint a grant, because the
+        // offer authority is checked against the OWNING tenant, not the grantee tenant.
+        if (typeof input.offeredBy !== 'string' || input.offeredBy.length === 0) {
+            throw new GrantNotPermittedError(`a non-empty offeredBy (the authenticated principal) is required.`);
+        }
+        const mayShare = await this.resolveAuthority(() => this.authorize(input.offeredBy, input.owningTenantId, 'share'));
+        if (mayShare !== true) {
+            throw new GrantNotPermittedError(`principal lacks 'share' authority in the owning tenant — cannot offer a cross-tenant grant.`);
+        }
+        const grantUuid = (0, node_crypto_1.randomUUID)();
+        // Store the ceiling as a JSON array (text — the JSON column accepts a valid JSON string).
+        const allowedActionsJson = JSON.stringify([...input.allowedActions]);
+        try {
+            await this.db.query(`INSERT INTO \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` (ctg_uuid, ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid,` +
+                `  ctg_grantee_kind, ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_record_uuid,` +
+                `  ctg_allowed_actions, ctg_status, ctg_offered_by, ctg_expires_at_ms)` +
+                ` VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'offered', ?, ?)`, [
+                grantUuid,
+                input.owningTenantId,
+                input.granteeTenantId,
+                input.granteeKind,
+                input.granteeUuid,
+                input.typeKey,
+                input.scope,
+                input.scope === 'record' ? (input.recordId ?? null) : null,
+                allowedActionsJson,
+                input.offeredBy,
+                // Expiry stored as BIGINT epoch-ms (timezone-immune — MUST-FIX #1). Bind the integer
+                // directly; NEVER `new Date(...)` (which serializes to a TZ-skewed wall-clock TIMESTAMP).
+                input.expiresAtMs,
+            ]);
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant offer write failed for ${input.typeKey}: ${err.message}`);
+        }
+        await this.emit('grant.offered', {
+            occurredAtMs: this.now(),
+            actorId: input.offeredBy,
+            owningTenantId: input.owningTenantId,
+            granteeTenantId: input.granteeTenantId,
+            attributes: {
+                grantUuid,
+                typeKey: input.typeKey,
+                scope: input.scope,
+                ...(input.scope === 'record' && input.recordId ? { recordId: input.recordId } : {}),
+                granteeKind: input.granteeKind,
+                granteeUuid: input.granteeUuid,
+                allowedActions: [...input.allowedActions],
+            },
+        });
+        return grantUuid;
+    }
+    /**
+     * ACCEPT a grant — the GRANTEE tenant activates it. Only a MEMBER of the grant's grantee
+     * tenant may accept, and only a grant currently 'offered'. Moves it to 'accepted' (the point
+     * at which it becomes ACTIVE for `findActiveGrant`). Re-accepting an 'accepted' grant is a
+     * benign no-op; accepting a 'revoked' grant is rejected. Emits `grant.accepted`.
+     *
+     * @throws {@link GrantNotPermittedError} if the accepter is not a grantee-tenant member, the
+     *   grant does not exist, or it is not in 'offered' status.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async accept(input) {
+        const row = await this.fetchGrant(input.grantUuid);
+        if (!row) {
+            throw new GrantNotPermittedError(`grant not found — cannot accept.`); // no uuid in message
+        }
+        if (typeof input.acceptedBy !== 'string' || input.acceptedBy.length === 0) {
+            throw new GrantNotPermittedError(`a non-empty acceptedBy (the authenticated principal) is required.`);
+        }
+        // Idempotent no-op: already accepted ⇒ nothing to do (but still verify the actor has
+        // 'accept' authority in the grantee tenant, so a stranger cannot probe/replay). A principal
+        // only holds a grantee-tenant permission THROUGH membership there, so this one check covers
+        // both "is a member" and "may accept".
+        const mayAccept = await this.resolveAuthority(() => this.authorize(input.acceptedBy, row.ctg_grantee_tenant_uuid, 'accept'));
+        if (mayAccept !== true) {
+            throw new GrantNotPermittedError(`principal lacks 'accept' authority in the grantee tenant — cannot accept this grant.`);
+        }
+        if (row.ctg_status === 'accepted') {
+            return; // benign idempotent no-op
+        }
+        if (row.ctg_status !== 'offered') {
+            // 'revoked' (dead) — must be re-offered, not re-accepted.
+            throw new GrantNotPermittedError(`grant is not in an offerable state — cannot accept.`);
+        }
+        try {
+            await this.db.query(`UPDATE \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` SET ctg_status = 'accepted', ctg_accepted_at = ?` +
+                ` WHERE ctg_uuid = ? AND ctg_status = 'offered'`, [new Date(this.now()), input.grantUuid]);
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant accept write failed: ${err.message}`);
+        }
+        await this.emitFromRow('grant.accepted', row, input.grantUuid, input.acceptedBy);
+    }
+    /**
+     * REVOKE a grant — EITHER an admin of the owning tenant OR a member of the grantee tenant may
+     * revoke (either side, ADR-0009). Moves it to 'revoked' + stamps `ctg_revoked_at` (it becomes
+     * immediately inactive — `findActiveGrant` reads live). Re-revoking a 'revoked' grant is a
+     * benign no-op. Emits `grant.revoked`.
+     *
+     * @throws {@link GrantNotPermittedError} if the revoker is neither an owning-tenant admin nor
+     *   a grantee-tenant member, or the grant does not exist.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async revoke(input) {
+        const row = await this.fetchGrant(input.grantUuid);
+        if (!row) {
+            throw new GrantNotPermittedError(`grant not found — cannot revoke.`); // no uuid in message
+        }
+        if (typeof input.revokedBy !== 'string' || input.revokedBy.length === 0) {
+            throw new GrantNotPermittedError(`a non-empty revokedBy (the authenticated principal) is required.`);
+        }
+        // Either side may revoke (ADR-0009): 'revoke' authority in the OWNING tenant OR in the
+        // GRANTEE tenant. Check owning-side first, then grantee-side; a principal with neither is a
+        // stranger and is rejected. (Each check is a `decide()` in that tenant, so it implies
+        // membership there too.)
+        const mayRevokeOwning = await this.resolveAuthority(() => this.authorize(input.revokedBy, row.ctg_owning_tenant_uuid, 'revoke'));
+        let permitted = mayRevokeOwning === true;
+        if (!permitted) {
+            const mayRevokeGrantee = await this.resolveAuthority(() => this.authorize(input.revokedBy, row.ctg_grantee_tenant_uuid, 'revoke'));
+            permitted = mayRevokeGrantee === true;
+        }
+        if (!permitted) {
+            throw new GrantNotPermittedError(`principal lacks 'revoke' authority in either the owning or grantee tenant — cannot revoke this grant.`);
+        }
+        if (row.ctg_status === 'revoked') {
+            return; // benign idempotent no-op
+        }
+        try {
+            await this.db.query(`UPDATE \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` SET ctg_status = 'revoked', ctg_revoked_at = ?` +
+                ` WHERE ctg_uuid = ? AND ctg_status <> 'revoked'`, [new Date(this.now()), input.grantUuid]);
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant revoke write failed: ${err.message}`);
+        }
+        await this.emitFromRow('grant.revoked', row, input.grantUuid, input.revokedBy);
+    }
+    // --- validity + authority helpers ------------------------------------------
+    /**
+     * Enforce the offer INPUT bounds (ceiling non-empty + non-wildcard, future expiry, scope ↔
+     * recordId). Throws {@link InvalidGrantError} on any failure (fail-closed). The is-admin
+     * authority check is done separately (it needs I/O).
+     */
+    assertValidOffer(input) {
+        // Ceiling: non-empty AND non-wildcard AND all-strings. A wildcard `'*'` is a hard reject —
+        // the ceiling must be an explicit enumerated set (ADR-0009).
+        const actions = input.allowedActions;
+        if (!Array.isArray(actions) || actions.length === 0) {
+            throw new InvalidGrantError(`allowedActions must be a non-empty set.`);
+        }
+        for (const a of actions) {
+            if (typeof a !== 'string' || a.length === 0) {
+                throw new InvalidGrantError(`allowedActions must contain only non-empty action keys.`);
+            }
+            if (a === '*') {
+                throw new InvalidGrantError(`allowedActions must not contain a wildcard '*' — the ceiling is explicit.`);
+            }
+        }
+        // Expiry: a finite FUTURE timestamp (mandatory, no perpetual/absent/past).
+        if (typeof input.expiresAtMs !== 'number' || !Number.isFinite(input.expiresAtMs)) {
+            throw new InvalidGrantError(`expiresAtMs must be a finite timestamp.`);
+        }
+        if (input.expiresAtMs <= this.now()) {
+            throw new InvalidGrantError(`expiresAtMs must be in the future — no perpetual/expired grants.`);
+        }
+        // Scope ↔ recordId: 'record' requires one; 'object_type' forbids one.
+        if (input.scope === 'record') {
+            if (typeof input.recordId !== 'string' || input.recordId.length === 0) {
+                throw new InvalidGrantError(`a record-scoped grant requires a non-empty recordId.`);
+            }
+        }
+        else if (input.scope === 'object_type') {
+            if (input.recordId !== undefined) {
+                throw new InvalidGrantError(`an object_type-scoped grant must not carry a recordId.`);
+            }
+        }
+        else {
+            throw new InvalidGrantError(`scope must be 'object_type' or 'record'.`);
+        }
+        // Tenant sanity: both tenants non-empty (a grant spans two DISTINCT tenants).
+        if (typeof input.owningTenantId !== 'string' || input.owningTenantId.length === 0) {
+            throw new InvalidGrantError(`a non-empty owningTenantId is required.`);
+        }
+        if (typeof input.granteeTenantId !== 'string' || input.granteeTenantId.length === 0) {
+            throw new InvalidGrantError(`a non-empty granteeTenantId is required.`);
+        }
+    }
+    /**
+     * Run an authority resolver call, translating a store outage into
+     * {@link GrantStoreUnavailableError} (retryable) — a resolver that THROWS is an outage, not a
+     * "not authorized". A resolver returning `false` is a legitimate deny (handled by the caller).
+     */
+    async resolveAuthority(fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`grant authority resolver unavailable: ${err.message}`);
+        }
+    }
+    /** Fetch a grant's lifecycle row (tenants + status) by uuid — never trusts caller-supplied tenants. */
+    async fetchGrant(grantUuid) {
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid, ctg_grantee_kind,` +
+                `       ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_record_uuid,` +
+                `       ctg_allowed_actions, ctg_status` +
+                ` FROM \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` WHERE ctg_uuid = ? LIMIT 1`, [grantUuid]));
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant read failed: ${err.message}`);
+        }
+        return rows[0];
+    }
+    // --- audit -----------------------------------------------------------------
+    /** Emit an offer event (fields already assembled). Best-effort. */
+    async emit(action, detail) {
+        if (!this.audit)
+            return;
+        const event = { type: 'cross_tenant_grant', action, ...detail };
+        try {
+            await this.audit.record(event);
+        }
+        catch {
+            // Best-effort: an audit failure must not fail a legitimate lifecycle operation.
+        }
+    }
+    /** Emit an accept/revoke event, deriving structured attributes from the fetched row. */
+    async emitFromRow(action, row, grantUuid, actorId) {
+        if (!this.audit)
+            return;
+        const scope = row.ctg_scope === 'record' ? 'record' : 'object_type';
+        // Array-aware (driver auto-parses the JSON column) — NEVER a bare JSON.parse on an array.
+        const allowedActions = parseCeiling(row.ctg_allowed_actions);
+        await this.emit(action, {
+            occurredAtMs: this.now(),
+            actorId,
+            owningTenantId: row.ctg_owning_tenant_uuid,
+            granteeTenantId: row.ctg_grantee_tenant_uuid,
+            attributes: {
+                grantUuid,
+                typeKey: row.ctg_type_key,
+                scope,
+                ...(scope === 'record' && row.ctg_record_uuid ? { recordId: row.ctg_record_uuid } : {}),
+                granteeKind: row.ctg_grantee_kind === 'role' ? 'role' : 'user',
+                granteeUuid: row.ctg_grantee_uuid,
+                allowedActions,
+            },
+        });
+    }
+}
+exports.CrossTenantGrantWriter = CrossTenantGrantWriter;

package/dist/authz/manifest-operation-authority-adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `ManifestOperationAuthorityAdapter` — the concrete {@link OperationAuthorityPort} for
+ * `@astram/guard`, backed by a DECLARED operation manifest (ADR-0008). It answers
+ * `resolveDelegatedAuthority(operationKey, stepKey)`: what scoped, non-wildcard authority does
+ * a trusted operation's step carry?
+ *
+ * ── WHAT DELEGATED AUTHORITY IS (ADR-0008 / gate 7): one server operation performs an internal
+ *    side-effect on an object type the CALLER may not touch directly (e.g. "create user" also
+ *    writes an onboarding record in a separate object type). That internal step must run under
+ *    the OPERATION'S OWN declared, scoped, least-privilege authority — NOT the caller's grants,
+ *    and NEVER a wildcard "skip all checks". This adapter resolves THAT declared authority.
+ *
+ * ── PURE, NO DB (ADR-0008). This is DECLARED metadata — the operation's own manifest, known at
+ *    build/registration time. So the lookup is SYNCHRONOUS and in-memory (no store, no I/O). The
+ *    port is contracted synchronous; a manifest is the natural backing.
+ *
+ * ── THE MANIFEST: `${operationKey}:${stepKey}` → {@link DelegatedAuthority}. The consumer
+ *    DECLARES it by constructing the adapter with a map (or `[key, authority]` entries). An
+ *    UNKNOWN key ⇒ `undefined` (pass-through: NO delegation — evaluate under the caller — the
+ *    common case).
+ *
+ * ── FAIL-CLOSED ON A MALFORMED / WILDCARD ENTRY. Core's gate-7 overlay re-checks scope with
+ *    strict membership, but this adapter NEVER hands back a wildcard or malformed authority: a
+ *    declared entry whose `objectTypeKeys` / `allowedActions` is not a non-empty array of
+ *    non-empty strings, OR contains a wildcard `'*'`, is treated as UNDEFINED (no delegation).
+ *    An operation cannot accidentally (or maliciously) declare a `'*'` and gain a root
+ *    reach — the malformed declaration simply grants no delegated authority.
+ *
+ * ── EMPTY MANIFEST = every lookup returns `undefined` = pass-through everywhere. A consumer with
+ *    no trusted operations yet wires this with an empty manifest — identical runtime behavior to
+ *    the interim `emptyOperationAuthority`, but now a REAL, declared surface ready for the first
+ *    trusted operation.
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): core defines the PORT + the gate-7 overlay that consumes it;
+ *    the manifest-backed concrete lives in guard and is injected into the wired decision
+ *    authority. It uses `@astram/core` TYPES only (erased at build).
+ */
+import type { DelegatedAuthority, OperationAuthorityPort } from '@astram/core';
+/** The DI token the adapter is bound under (parity with the other authz-port tokens). */
+export declare const SHIELD_OPERATION_AUTHORITY_PORT: unique symbol;
+/**
+ * A single declared operation-step authority. Mirrors core's {@link DelegatedAuthority} (a
+ * scoped, NON-wildcard object-type + action ceiling) — declared by the consumer per trusted
+ * operation step.
+ */
+export interface OperationManifestEntry {
+    /** The trusted operation's stable key (its manifest identity). */
+    readonly operationKey: string;
+    /** The specific internal step within the operation. */
+    readonly stepKey: string;
+    /** The declared authority the step carries (scoped, non-wildcard). */
+    readonly authority: DelegatedAuthority;
+}
+export declare class ManifestOperationAuthorityAdapter implements OperationAuthorityPort {
+    private readonly manifest;
+    /**
+     * @param entries the declared operation-step authorities. Each malformed / wildcard entry is
+     *   DROPPED at construction (fail-closed) — it will resolve to `undefined` (no delegation)
+     *   rather than ever hand back an unsafe authority. A duplicate `${op}:${step}` key keeps the
+     *   LAST well-formed declaration.
+     */
+    constructor(entries?: readonly OperationManifestEntry[]);
+    resolveDelegatedAuthority(operationKey: string, stepKey: string): DelegatedAuthority | undefined;
+}
+//# sourceMappingURL=manifest-operation-authority-adapter.d.ts.map

package/dist/authz/manifest-operation-authority-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-operation-authority-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/manifest-operation-authority-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE/E,yFAAyF;AACzF,eAAO,MAAM,+BAA+B,eAA4C,CAAC;AAEzF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;CACxC;AA6BD,qBAAa,iCAAkC,YAAW,sBAAsB;IAC9E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAE3D;;;;;OAKG;gBACS,OAAO,GAAE,SAAS,sBAAsB,EAAO;IAuB3D,yBAAyB,CACvB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,kBAAkB,GAAG,SAAS;CAalC"}

package/dist/authz/manifest-operation-authority-adapter.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * `ManifestOperationAuthorityAdapter` — the concrete {@link OperationAuthorityPort} for
+ * `@astram/guard`, backed by a DECLARED operation manifest (ADR-0008). It answers
+ * `resolveDelegatedAuthority(operationKey, stepKey)`: what scoped, non-wildcard authority does
+ * a trusted operation's step carry?
+ *
+ * ── WHAT DELEGATED AUTHORITY IS (ADR-0008 / gate 7): one server operation performs an internal
+ *    side-effect on an object type the CALLER may not touch directly (e.g. "create user" also
+ *    writes an onboarding record in a separate object type). That internal step must run under
+ *    the OPERATION'S OWN declared, scoped, least-privilege authority — NOT the caller's grants,
+ *    and NEVER a wildcard "skip all checks". This adapter resolves THAT declared authority.
+ *
+ * ── PURE, NO DB (ADR-0008). This is DECLARED metadata — the operation's own manifest, known at
+ *    build/registration time. So the lookup is SYNCHRONOUS and in-memory (no store, no I/O). The
+ *    port is contracted synchronous; a manifest is the natural backing.
+ *
+ * ── THE MANIFEST: `${operationKey}:${stepKey}` → {@link DelegatedAuthority}. The consumer
+ *    DECLARES it by constructing the adapter with a map (or `[key, authority]` entries). An
+ *    UNKNOWN key ⇒ `undefined` (pass-through: NO delegation — evaluate under the caller — the
+ *    common case).
+ *
+ * ── FAIL-CLOSED ON A MALFORMED / WILDCARD ENTRY. Core's gate-7 overlay re-checks scope with
+ *    strict membership, but this adapter NEVER hands back a wildcard or malformed authority: a
+ *    declared entry whose `objectTypeKeys` / `allowedActions` is not a non-empty array of
+ *    non-empty strings, OR contains a wildcard `'*'`, is treated as UNDEFINED (no delegation).
+ *    An operation cannot accidentally (or maliciously) declare a `'*'` and gain a root
+ *    reach — the malformed declaration simply grants no delegated authority.
+ *
+ * ── EMPTY MANIFEST = every lookup returns `undefined` = pass-through everywhere. A consumer with
+ *    no trusted operations yet wires this with an empty manifest — identical runtime behavior to
+ *    the interim `emptyOperationAuthority`, but now a REAL, declared surface ready for the first
+ *    trusted operation.
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): core defines the PORT + the gate-7 overlay that consumes it;
+ *    the manifest-backed concrete lives in guard and is injected into the wired decision
+ *    authority. It uses `@astram/core` TYPES only (erased at build).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManifestOperationAuthorityAdapter = exports.SHIELD_OPERATION_AUTHORITY_PORT = void 0;
+/** The DI token the adapter is bound under (parity with the other authz-port tokens). */
+exports.SHIELD_OPERATION_AUTHORITY_PORT = Symbol('SHIELD_OPERATION_AUTHORITY_PORT');
+/** Compose the internal manifest map key from an operation + step. */
+function manifestKey(operationKey, stepKey) {
+    return `${operationKey}:${stepKey}`;
+}
+/**
+ * Whether a declared authority is WELL-FORMED and non-wildcard: both `objectTypeKeys` and
+ * `allowedActions` must be non-empty arrays of non-empty strings, and NEITHER may contain a
+ * wildcard `'*'`. A malformed / wildcard authority is rejected (⇒ treated as no delegation).
+ */
+function isWellFormedAuthority(authority) {
+    if (!authority || typeof authority !== 'object')
+        return false;
+    return (isNonEmptyExplicitStringArray(authority.objectTypeKeys) &&
+        isNonEmptyExplicitStringArray(authority.allowedActions));
+}
+/** A non-empty array of non-empty strings, NONE of which is a wildcard `'*'`. */
+function isNonEmptyExplicitStringArray(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return false;
+    for (const v of value) {
+        if (typeof v !== 'string' || v.length === 0 || v === '*')
+            return false;
+    }
+    return true;
+}
+class ManifestOperationAuthorityAdapter {
+    manifest;
+    /**
+     * @param entries the declared operation-step authorities. Each malformed / wildcard entry is
+     *   DROPPED at construction (fail-closed) — it will resolve to `undefined` (no delegation)
+     *   rather than ever hand back an unsafe authority. A duplicate `${op}:${step}` key keeps the
+     *   LAST well-formed declaration.
+     */
+    constructor(entries = []) {
+        this.manifest = new Map();
+        for (const entry of entries) {
+            if (typeof entry.operationKey !== 'string' ||
+                entry.operationKey.length === 0 ||
+                typeof entry.stepKey !== 'string' ||
+                entry.stepKey.length === 0) {
+                continue; // malformed key — skip
+            }
+            if (!isWellFormedAuthority(entry.authority)) {
+                continue; // malformed / wildcard authority — skip (fail-closed → undefined)
+            }
+            // Freeze a defensive copy so a later mutation of the caller's arrays cannot widen it.
+            const frozen = {
+                objectTypeKeys: Object.freeze([...entry.authority.objectTypeKeys]),
+                allowedActions: Object.freeze([...entry.authority.allowedActions]),
+            };
+            this.manifest.set(manifestKey(entry.operationKey, entry.stepKey), frozen);
+        }
+    }
+    resolveDelegatedAuthority(operationKey, stepKey) {
+        if (typeof operationKey !== 'string' ||
+            operationKey.length === 0 ||
+            typeof stepKey !== 'string' ||
+            stepKey.length === 0) {
+            return undefined; // malformed lookup key ⇒ pass-through
+        }
+        // A present entry is already validated + frozen at construction — return it as-is. An
+        // absent key ⇒ undefined (pass-through: no delegation, the common case).
+        return this.manifest.get(manifestKey(operationKey, stepKey));
+    }
+}
+exports.ManifestOperationAuthorityAdapter = ManifestOperationAuthorityAdapter;