@substrat-run/kernel 0.114.0 → 0.117.0

package/dist/capability.js

@@ -0,0 +1,537 @@
+import { CAPABILITY_EXERCISED, CAPABILITY_MINTED, CAPABILITY_REVOKED, CAPABILITY_SECRET_PREFIX, CAPABILITY_SESSION_PREFIX, CAPABILITY_SESSION_TTL_MS, becomeCapabilityInput, capabilityAuthor, capabilityFilter, capabilityId as capabilityIdSchema, capabilityMintInput, capabilityRecord, permissionKey, principalId as principalIdSchema, substratError, } from '@substrat-run/contracts';
+import { PermissionDenied } from './permission-checker.js';
+import { ulid } from './ulid.js';
+/**
+ * The two spine tables, kernel-owned so no vertical carries a migration for them. Shared by
+ * both adapters' `KERNEL_DDL` (interpolated, like `IDEMPOTENCY_DDL`), so the shape
+ * self-host builds and the shape production builds cannot part company.
+ */
+export const CAPABILITY_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_capabilities (
+    id TEXT PRIMARY KEY,
+    -- #1672: SHA-256 hex of the secret. The secret itself is stored NOWHERE — it leaves
+    -- the kernel once, in the mint's return value, and a lookup is this indexed equality.
+    token_hash TEXT NOT NULL UNIQUE,
+    -- 'act': the holder acts AS the capability ({ capability } on the spine), bounded by
+    -- entity + permissions (+ operations). 'become': exchanging it yields \`principal\`.
+    mode TEXT NOT NULL,
+    label TEXT,
+    entity_type TEXT,
+    entity_id TEXT,
+    -- JSON array of permission keys (act). The capability's whole authority: no
+    -- \`capability:\` tuple is ever written, so none can be forged through the tuple table.
+    permissions TEXT,
+    -- JSON array of operation names, or NULL = any operation the keys allow (act).
+    operations TEXT,
+    principal TEXT,
+    -- JSON capabilityAuthor: a principal id (a module minted it, and its authority is
+    -- re-checked on every use) or {"platform": …} (HostAdmin minted it).
+    minted_by TEXT NOT NULL,
+    minted_at TEXT NOT NULL,
+    expires_at TEXT,
+    -- NULL = unlimited. A use is an EXCHANGE of the secret, never an invocation.
+    max_uses INTEGER,
+    uses INTEGER NOT NULL DEFAULT 0,
+    last_used_at TEXT,
+    -- Tombstone, never a delete: a capability that once admitted someone is evidence
+    -- of why they were admitted (K-4, K-21).
+    revoked_at TEXT,
+    revoked_by TEXT
+  );
+  CREATE INDEX IF NOT EXISTS _substrat_capabilities_entity
+    ON _substrat_capabilities (entity_type, entity_id);
+  -- #1672: what an exchange hands out instead of the secret — a session token, of which
+  -- again only the hash is kept. Each session acts as its capability until the earlier of
+  -- its own expiry and the capability's; the capability is re-read on every invoke, so
+  -- revoking it ends every session at once — a revoke touches only the capability row,
+  -- and it is that per-invoke read, not a cascade here, that refuses the next call.
+  -- Expired rows are pruned on exchange, at most CAPABILITY_SESSION_PRUNE_BATCH at a time,
+  -- on the only path that adds one — so an exchange's write is bounded however many expired.
+  CREATE TABLE IF NOT EXISTS _substrat_capability_sessions (
+    token_hash TEXT PRIMARY KEY,
+    capability_id TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS _substrat_capability_sessions_expiry
+    ON _substrat_capability_sessions (expires_at);
+`;
+/** Every column a read returns — everything but `token_hash`, which no reader has a use for. */
+export const CAPABILITY_COLUMNS = 'id, mode, label, entity_type, entity_id, permissions, operations, principal, minted_by, ' +
+    'minted_at, expires_at, max_uses, uses, last_used_at, revoked_at, revoked_by';
+/** The row the permission checker reads for a capability subject (`ScopeTupleReader.capability`). */
+export function capabilityByIdQuery(id) {
+    return {
+        sql: `SELECT ${CAPABILITY_COLUMNS} FROM _substrat_capabilities WHERE id = ?`,
+        params: [id],
+    };
+}
+/**
+ * Is this capability USABLE — not revoked, not expired? The ONE predicate for it: the
+ * permission checker, the session door and the exchange all call this, so the three can
+ * never disagree about whether a revoked or expired capability still acts. Same shape as
+ * the evaluator's `live()` for tuples, and ISO instants compare lexically.
+ */
+export const capabilityLive = (row, now) => row.revoked_at === null && (row.expires_at === null || row.expires_at > now);
+/**
+ * May this capability's secret be EXCHANGED now — usable, and under its use limit? The use
+ * limit bounds exchanges only: a session handed out by an earlier exchange keeps acting
+ * after the limit is reached, until the capability expires or is revoked.
+ */
+export const capabilityExchangeable = (row, now) => capabilityLive(row, now) && (row.max_uses === null || row.uses < row.max_uses);
+export function capabilityGrantOf(row) {
+    if (row.mode !== 'act' || row.entity_type === null || row.entity_id === null)
+        return null;
+    try {
+        const permissions = JSON.parse(row.permissions ?? 'null').map((p) => permissionKey.parse(p));
+        const author = capabilityAuthor.parse(JSON.parse(row.minted_by));
+        return {
+            entity: { entityType: row.entity_type, entityId: row.entity_id },
+            permissions,
+            mintedBy: typeof author === 'string' ? author : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** The record a caller reads back — never the secret, never its hash. */
+export function capabilityRecordOf(row) {
+    const common = {
+        id: row.id,
+        label: row.label,
+        mintedBy: JSON.parse(row.minted_by),
+        mintedAt: row.minted_at,
+        expiresAt: row.expires_at,
+        maxUses: row.max_uses,
+        uses: row.uses,
+        lastUsedAt: row.last_used_at,
+        revokedAt: row.revoked_at,
+        revokedBy: row.revoked_by === null ? null : JSON.parse(row.revoked_by),
+    };
+    return capabilityRecord.parse(row.mode === 'become'
+        ? { mode: 'become', ...common, principal: row.principal }
+        : {
+            mode: 'act',
+            ...common,
+            entity: { entityType: row.entity_type, entityId: row.entity_id },
+            permissions: JSON.parse(row.permissions ?? '[]'),
+            operations: row.operations === null ? null : JSON.parse(row.operations),
+        });
+}
+const b64url = (bytes) => {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+/** A fresh capability secret: 256 bits, base64url, prefixed. Only its hash is ever stored. */
+export function mintCapabilitySecret() {
+    return CAPABILITY_SECRET_PREFIX + b64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/** A fresh session token — the same construction, its own prefix. */
+export function mintCapabilitySessionToken() {
+    return CAPABILITY_SESSION_PREFIX + b64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/**
+ * SHA-256 hex of a secret or session token (Web Crypto — the same call in workerd, node and
+ * browsers). Unkeyed on purpose: with 256 bits of entropy there is no dictionary to defend
+ * against, and a key would be one more secret to hold and rotate.
+ */
+export async function capabilityTokenHash(token) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token));
+    let hex = '';
+    for (const b of new Uint8Array(buf))
+        hex += b.toString(16).padStart(2, '0');
+    return hex;
+}
+/**
+ * How many expired sessions one exchange prunes, at most. An unlimited link can hand out any
+ * number of sessions, so pruning every expired row at once would make one visitor's request
+ * an unbounded write — and a Durable Object's transaction a large one. A fixed batch keeps
+ * each exchange's cost constant, and the table still drains: every exchange takes another
+ * batch, and an expired session acts as nobody whether or not it has been pruned yet.
+ */
+export const CAPABILITY_SESSION_PRUNE_BATCH = 100;
+/** A secret or token that cannot be one of ours is refused before it is ever hashed. */
+const TOKEN_MAX_LENGTH = 128;
+const plausible = (token, prefix) => typeof token === 'string' && token.startsWith(prefix) && token.length <= TOKEN_MAX_LENGTH;
+const decodeBytes = (bytes) => new TextDecoder().decode(bytes);
+/**
+ * The text a value would persist as — ONE serialization of the COMPLETE record, keys
+ * included, byte values decoded as UTF-8. The guard scans this rather than walking chosen
+ * fields, so a secret used as an entity id, a request kind, an object key or a BLOB
+ * parameter is found exactly as one in a payload value is: there is no field list to
+ * forget a field from. The secret's alphabet (base64url behind `sbcap_`) contains nothing
+ * JSON escapes, so the serialization contains the secret exactly when the value does.
+ */
+export function persistedText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Uint8Array)
+        return decodeBytes(value);
+    return (JSON.stringify(value, (_key, v) => v instanceof Uint8Array ? decodeBytes(v) : typeof v === 'bigint' ? v.toString() : v) ?? '');
+}
+/** Does `value`, serialized as it would persist (`persistedText`), contain any of `secrets`? */
+export function carriesSecret(value, secrets) {
+    if (secrets.length === 0)
+        return false;
+    const text = persistedText(value);
+    return secrets.some((s) => text.includes(s));
+}
+/** What a recorded response carries in place of a minted secret. */
+export const WITHHELD_SECRET = '[capability secret withheld]';
+/**
+ * `value` with every minted secret replaced by `WITHHELD_SECRET` — what an idempotency
+ * recording stores. A replayed mint therefore returns the placeholder, never the secret:
+ * the caller that lost the first response mints again, which is the honest outcome, since
+ * the alternative is a plaintext secret in a spine table for a day.
+ *
+ * Done on the serialization, like the guard, so a secret in a key is withheld as surely as
+ * one in a value. The recording is JSON already, so round-tripping through it changes
+ * nothing the recording would have kept — and a value carrying no secret is returned as is.
+ */
+export function redactSecrets(value, secrets) {
+    if (value === undefined || !carriesSecret(value, secrets))
+        return value;
+    let text = persistedText(value);
+    for (const s of secrets)
+        text = text.split(s).join(WITHHELD_SECRET);
+    return JSON.parse(text);
+}
+/**
+ * The tripwire (see above): refuse a write whose COMPLETE record, as it would persist,
+ * carries a secret this invocation minted. Thrown from `ctx.emit` (the whole parsed event),
+ * `ctx.requestPlatform` (the whole parsed request) and `ctx.sql` (the statement and every
+ * parameter, bytes decoded) while the minting invocation runs.
+ */
+export function assertNoSecret(where, record, secrets) {
+    if (carriesSecret(record, secrets)) {
+        throw substratError('forbidden', `${where} would store a capability secret. Only its hash is ever kept — return the ` +
+            'secret to the caller once, and never write it to a row or an event.', { reason: 'capability_secret' });
+    }
+}
+/** `ctx.sql` with every statement — its text and all its parameters — held to `assertNoSecret`. */
+export function guardSecrets(inner, secrets) {
+    return {
+        query: (sql, params) => {
+            assertNoSecret('ctx.sql', [sql, ...(params ?? [])], secrets);
+            return inner.query(sql, params);
+        },
+        exec: (sql, params) => {
+            assertNoSecret('ctx.sql', [sql, ...(params ?? [])], secrets);
+            return inner.exec(sql, params);
+        },
+    };
+}
+const refToString = (e) => `${e.entityType}:${e.entityId}`;
+function principalOf(subject, verb) {
+    if (subject.kind !== 'principal') {
+        throw substratError('forbidden', `${verb}: only a principal may ${verb.endsWith('mint') ? 'mint' : 'revoke'} a capability — ` +
+            `a ${subject.kind} actor cannot delegate authority it holds on someone else's behalf`, { reason: 'capability_delegation' });
+    }
+    return subject.id;
+}
+export function createCapabilityVerbs(deps) {
+    const readRow = (id) => {
+        const q = capabilityByIdQuery(id);
+        return deps.sql.query(q.sql, q.params)[0];
+    };
+    return {
+        async mint(raw) {
+            deps.assertWrites('ctx.capabilities.mint');
+            const minter = principalOf(deps.subject, 'ctx.capabilities.mint');
+            const input = capabilityMintInput.parse(raw);
+            const permissions = [...new Set(input.permissions)];
+            const operations = input.operations ? [...new Set(input.operations)] : null;
+            for (const op of operations ?? []) {
+                if (!deps.isOperation(op)) {
+                    throw substratError('validation_failed', `ctx.capabilities.mint: '${op}' is not an operation on this host — an allowlist ` +
+                        'naming nothing would read as a narrowing and narrow nothing');
+                }
+            }
+            if (input.expiresAt !== undefined && input.expiresAt <= deps.now) {
+                throw substratError('validation_failed', `ctx.capabilities.mint: expiresAt ${input.expiresAt} is not in the future`);
+            }
+            // Delegation, never elevation — the SAME check the operation passes, per key, on the
+            // entity. A plain `PermissionDenied` with no detail, like `ctx.grant`'s refusal: it is
+            // the module's attempt that failed, and K-35 records enforced checks, not this.
+            for (const permission of permissions) {
+                const held = await deps.check(permission, input.entity);
+                if (!held.allowed) {
+                    throw new PermissionDenied(`cannot mint a capability carrying '${permission}' on ${refToString(input.entity)} — ` +
+                        'the caller does not hold it there (a capability delegates, it never elevates)');
+                }
+            }
+            const id = capabilityIdSchema.parse(ulid());
+            const secret = mintCapabilitySecret();
+            const tokenHash = await capabilityTokenHash(secret);
+            deps.sql.exec(`INSERT INTO _substrat_capabilities
+           (id, token_hash, mode, label, entity_type, entity_id, permissions, operations,
+            principal, minted_by, minted_at, expires_at, max_uses, uses)
+         VALUES (?, ?, 'act', ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, 0)`, [
+                id,
+                tokenHash,
+                input.label ?? null,
+                input.entity.entityType,
+                input.entity.entityId,
+                JSON.stringify(permissions),
+                operations === null ? null : JSON.stringify(operations),
+                JSON.stringify(minter),
+                deps.now,
+                input.expiresAt ?? null,
+                input.maxUses ?? null,
+            ]);
+            deps.minted.push(secret);
+            const payload = {
+                capabilityId: id,
+                entity: input.entity,
+                permissions,
+                operations,
+                expiresAt: input.expiresAt ?? null,
+                maxUses: input.maxUses ?? null,
+                label: input.label ?? null,
+                mintedBy: minter,
+            };
+            deps.emit({
+                type: CAPABILITY_MINTED,
+                schemaVersion: 1,
+                entity: input.entity,
+                piiClass: 'none',
+                payload,
+            });
+            return { id, secret, expiresAt: input.expiresAt ?? null };
+        },
+        async revoke(rawId) {
+            deps.assertWrites('ctx.capabilities.revoke');
+            const revoker = principalOf(deps.subject, 'ctx.capabilities.revoke');
+            const id = capabilityIdSchema.parse(rawId);
+            const row = readRow(id);
+            if (!row)
+                throw substratError('not_found', `no capability ${id} in this scope`);
+            const grant = capabilityGrantOf(row);
+            if (!grant) {
+                throw substratError('forbidden', `capability ${id} was minted by the platform and is revoked through HostAdmin`, { reason: 'capability_platform_minted' });
+            }
+            if (row.revoked_at !== null)
+                return;
+            for (const permission of grant.permissions) {
+                const held = await deps.check(permission, grant.entity);
+                if (!held.allowed) {
+                    throw new PermissionDenied(`cannot revoke capability ${id} — the caller does not hold '${permission}' on ` +
+                        `${refToString(grant.entity)} (a revoke is open to whoever could have minted it)`);
+                }
+            }
+            deps.sql.exec(`UPDATE _substrat_capabilities SET revoked_at = ?, revoked_by = ?
+         WHERE id = ? AND revoked_at IS NULL`, [deps.now, JSON.stringify(revoker), id]);
+            const payload = {
+                capabilityId: id,
+                entity: grant.entity,
+                revokedBy: revoker,
+            };
+            deps.emit({
+                type: CAPABILITY_REVOKED,
+                schemaVersion: 1,
+                entity: grant.entity,
+                piiClass: 'none',
+                payload,
+            });
+        },
+        list(raw) {
+            const filter = capabilityFilter.parse(raw ?? {});
+            const where = [];
+            const params = [];
+            if (filter.entity) {
+                where.push('entity_type = ? AND entity_id = ?');
+                params.push(filter.entity.entityType, filter.entity.entityId);
+            }
+            if (!filter.includeRevoked)
+                where.push('revoked_at IS NULL');
+            params.push(filter.limit ?? 50);
+            const rows = deps.sql.query(`SELECT ${CAPABILITY_COLUMNS} FROM _substrat_capabilities
+         ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+         ORDER BY id DESC LIMIT ?`, params);
+            return rows.map(capabilityRecordOf);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// The host-level verbs: exchange, the session door, and the platform's mint/revoke.
+// ---------------------------------------------------------------------------
+/** The pseudo-operation an exchange's spine event names, on `attachments.upload`'s pattern. */
+export const CAPABILITY_EXCHANGE_OPERATION = 'capabilities.exchange';
+/**
+ * Trade a secret for what it grants — ONE counted use. Runs inside the scope's
+ * serialization domain and a transaction the adapter opened; `emit` writes the
+ * `capability.exercised` event with the capability as its actor.
+ *
+ * The use is taken with an `UPDATE … WHERE uses = ?` on the row just read, so it is atomic
+ * even without the scope's single-writer guarantee: two exchanges racing for a single-use
+ * capability cannot both see `uses = 0` and both win.
+ *
+ * `null` for an unknown, expired, revoked or used-up secret — one answer for all four, so
+ * a caller probing for secrets learns nothing it can act on. Refused exchanges are not
+ * recorded: their volume is whatever an attacker chooses, and with 256 bits of entropy
+ * there is nothing a record of guesses would ever show (#130 is the rate control).
+ */
+export async function exchangeCapability(deps, secret, 
+/**
+ * The only mode the caller can handle. A secret of the OTHER mode answers `null` without
+ * taking a use: a claim link pasted into a share-link exchange must not be spent by a
+ * route that would then throw away the principal it yielded.
+ */
+mode) {
+    if (!plausible(secret, CAPABILITY_SECRET_PREFIX))
+        return null;
+    const tokenHash = await capabilityTokenHash(secret);
+    const row = deps.sql.query(`SELECT ${CAPABILITY_COLUMNS} FROM _substrat_capabilities WHERE token_hash = ?`, [tokenHash])[0];
+    if (!row || !capabilityExchangeable(row, deps.now))
+        return null;
+    if (mode !== undefined && row.mode !== mode)
+        return null;
+    const taken = deps.sql.exec(`UPDATE _substrat_capabilities SET uses = uses + 1, last_used_at = ?
+     WHERE id = ? AND uses = ?`, [deps.now, row.id, row.uses]);
+    if (taken.changes !== 1)
+        return null;
+    const id = capabilityIdSchema.parse(row.id);
+    const uses = row.uses + 1;
+    if (row.mode === 'become') {
+        const principal = principalIdSchema.parse(row.principal);
+        const payload = {
+            capabilityId: id,
+            mode: 'become',
+            uses,
+            maxUses: row.max_uses,
+            sessionExpiresAt: null,
+            principal,
+        };
+        deps.emit(id, {
+            type: CAPABILITY_EXERCISED,
+            schemaVersion: 1,
+            entity: { entityType: 'capability', entityId: id },
+            piiClass: 'none',
+            payload,
+        });
+        return { kind: 'principal', capabilityId: id, principal };
+    }
+    const grant = capabilityGrantOf(row);
+    if (!grant)
+        return null;
+    const ttlEnd = new Date(Date.parse(deps.now) + CAPABILITY_SESSION_TTL_MS).toISOString();
+    const expiresAt = (row.expires_at !== null && row.expires_at < ttlEnd
+        ? row.expires_at
+        : ttlEnd);
+    const sessionToken = mintCapabilitySessionToken();
+    // Bounded (see CAPABILITY_SESSION_PRUNE_BATCH) — a subquery LIMIT rather than
+    // `DELETE … LIMIT`, which SQLite accepts only when built with an option neither host
+    // promises. The expiry index makes the inner select a range seek.
+    deps.sql.exec(`DELETE FROM _substrat_capability_sessions WHERE token_hash IN (
+       SELECT token_hash FROM _substrat_capability_sessions WHERE expires_at <= ? LIMIT ?)`, [deps.now, CAPABILITY_SESSION_PRUNE_BATCH]);
+    deps.sql.exec(`INSERT INTO _substrat_capability_sessions (token_hash, capability_id, created_at, expires_at)
+     VALUES (?, ?, ?, ?)`, [await capabilityTokenHash(sessionToken), id, deps.now, expiresAt]);
+    const payload = {
+        capabilityId: id,
+        mode: 'act',
+        uses,
+        maxUses: row.max_uses,
+        sessionExpiresAt: expiresAt,
+        principal: null,
+    };
+    deps.emit(id, {
+        type: CAPABILITY_EXERCISED,
+        schemaVersion: 1,
+        entity: grant.entity,
+        piiClass: 'none',
+        payload,
+    });
+    return { kind: 'session', capabilityId: id, sessionToken, expiresAt, entity: grant.entity };
+}
+/**
+ * The session door's decision, re-made on EVERY invoke inside the operation's transaction
+ * (impersonation's per-invoke re-read, for the same reason): a stub is a capability of its
+ * own and nothing takes it away, so a revocation checked only when the stub was minted
+ * would stop everyone except the one caller holding it.
+ *
+ * Refuses an unknown or expired session and a revoked or expired capability as
+ * `unauthenticated` — the credential no longer works, and re-opening a live link is the
+ * remedy — and an operation outside the capability's allowlist as `forbidden`. None of
+ * these is a K-35 denial: no permission key was checked, and the denial log records
+ * enforced checks. The handler's own checks, once it runs, are.
+ */
+export function resolveCapabilitySession(sql, sessionHash, now, operation) {
+    const session = sql.query(`SELECT capability_id, expires_at FROM _substrat_capability_sessions WHERE token_hash = ?`, [sessionHash])[0];
+    if (!session || session.expires_at <= now) {
+        throw substratError('unauthenticated', 'capability session is unknown or has expired');
+    }
+    const q = capabilityByIdQuery(session.capability_id);
+    const row = sql.query(q.sql, q.params)[0];
+    if (!row || row.mode !== 'act' || !capabilityLive(row, now)) {
+        throw substratError('unauthenticated', 'capability has been revoked or has expired');
+    }
+    if (row.operations !== null) {
+        const allowed = JSON.parse(row.operations);
+        if (!allowed.includes(operation)) {
+            throw substratError('forbidden', `capability ${row.id} may not invoke '${operation}' — it is not on the capability's ` +
+                'operation list', { reason: 'capability_operation' });
+        }
+    }
+    return capabilityIdSchema.parse(row.id);
+}
+/** Is `token` shaped like a session token at all? Checked before it is hashed or sent anywhere. */
+export const plausibleSessionToken = (token) => plausible(token, CAPABILITY_SESSION_PREFIX);
+/**
+ * The platform's mint (`HostAdmin.mintCapability`) — a `become` capability, which is the
+ * only kind the platform mints and the only way one is minted in this first cut (see
+ * `becomeCapabilityInput`). No spine event: a platform actor's act is the admin log's to
+ * record, and the adapter records it there.
+ */
+/**
+ * A platform mint's input, parsed and held to its one rule beyond the shape: an expiry in
+ * the future. Its own function so a host whose storage sits across an RPC boundary can run
+ * it on the near side, where a typed refusal still reaches the caller as one — the same
+ * check `mintBecomeCapability` makes, not a second copy of it.
+ */
+export function checkBecomeInput(raw, now) {
+    const input = becomeCapabilityInput.parse(raw);
+    if (input.expiresAt <= now) {
+        throw substratError('validation_failed', `mintCapability: expiresAt ${input.expiresAt} is not in the future`);
+    }
+    return input;
+}
+export async function mintBecomeCapability(sql, raw, actor, now) {
+    const input = checkBecomeInput(raw, now);
+    const id = capabilityIdSchema.parse(ulid());
+    const secret = mintCapabilitySecret();
+    const author = { platform: actor };
+    sql.exec(`INSERT INTO _substrat_capabilities
+       (id, token_hash, mode, label, entity_type, entity_id, permissions, operations,
+        principal, minted_by, minted_at, expires_at, max_uses, uses)
+     VALUES (?, ?, 'become', ?, NULL, NULL, NULL, NULL, ?, ?, ?, ?, ?, 0)`, [
+        id,
+        await capabilityTokenHash(secret),
+        input.label ?? null,
+        input.principal,
+        JSON.stringify(author),
+        now,
+        input.expiresAt,
+        input.maxUses,
+    ]);
+    return { id, secret, expiresAt: input.expiresAt };
+}
+/**
+ * The platform's revoke (`HostAdmin.revokeCapability`) — of any capability in the scope,
+ * the operator's lever for a leaked link. Returns the row as it stood before, for the admin
+ * log, or `undefined` when there is no such capability. Idempotent.
+ */
+export function revokeCapabilityAsPlatform(sql, rawId, actor, now) {
+    const id = capabilityIdSchema.parse(rawId);
+    const q = capabilityByIdQuery(id);
+    const row = sql.query(q.sql, q.params)[0];
+    if (!row)
+        return undefined;
+    const author = { platform: actor };
+    sql.exec(`UPDATE _substrat_capabilities SET revoked_at = ?, revoked_by = ?
+     WHERE id = ? AND revoked_at IS NULL`, [now, JSON.stringify(author), id]);
+    return capabilityRecordOf(row);
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

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

package/dist/check-key.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The runtime half of `ctx.check`'s `PermissionKey` parameter (#1642).
+ *
+ * The brand is compile-time only, so a module that casts (`'Workorder:Read' as
+ * PermissionKey`) hands the host a string no manifest and no role could ever carry.
+ * Until this, both adapters took it on trust: the checker refused it (nothing holds
+ * it), the refusal was recorded in the denial log under a key that is not a
+ * permission, and the author read `permission denied` for what is a typo. On the
+ * system-actor path, which allows without consulting a grant, it went further: the
+ * key became the relation of the proof the check returned, and `ctx.grant` wrote it
+ * into `_substrat_tuples`.
+ *
+ * So both adapters call this FIRST in `runCheck` — above the system-actor early
+ * return, which is the path that never reaches the checker — and `ctx.grant` /
+ * `ctx.revoke` inherit it because they re-check through `runCheck` before writing.
+ *
+ * **Why a throw and not a denial.** Both refuse, so neither lets the call through:
+ * a throw returns no `Decision`, so there is nothing for `assertAllowed` to pass and
+ * nothing is added to the K-34 `authorization` the operation's events carry. A
+ * caller that catches it and carries on has skipped a check, exactly as one that
+ * never called `ctx.check` has — no more than that. What differs is who is told. A
+ * denial is a statement about a principal ("was refused X"), and X here is not a
+ * permission; recording it fills the denial log with rows that read as an
+ * authorization problem, and on the system-actor path a denial is not even an
+ * available answer. It is a bug in the module, so it is `internal` — a 500 whose
+ * `detail` never leaves the server — and the message names the key for the log.
+ */
+import { type PermissionKey } from '@substrat-run/contracts';
+export declare function assertPermissionKey(permission: unknown): PermissionKey;
+//# sourceMappingURL=check-key.d.ts.map

package/dist/check-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-key.d.ts","sourceRoot":"","sources":["../src/check-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE3F,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,OAAO,GAAG,aAAa,CAStE"}

package/dist/check-key.js

@@ -0,0 +1,37 @@
+/**
+ * The runtime half of `ctx.check`'s `PermissionKey` parameter (#1642).
+ *
+ * The brand is compile-time only, so a module that casts (`'Workorder:Read' as
+ * PermissionKey`) hands the host a string no manifest and no role could ever carry.
+ * Until this, both adapters took it on trust: the checker refused it (nothing holds
+ * it), the refusal was recorded in the denial log under a key that is not a
+ * permission, and the author read `permission denied` for what is a typo. On the
+ * system-actor path, which allows without consulting a grant, it went further: the
+ * key became the relation of the proof the check returned, and `ctx.grant` wrote it
+ * into `_substrat_tuples`.
+ *
+ * So both adapters call this FIRST in `runCheck` — above the system-actor early
+ * return, which is the path that never reaches the checker — and `ctx.grant` /
+ * `ctx.revoke` inherit it because they re-check through `runCheck` before writing.
+ *
+ * **Why a throw and not a denial.** Both refuse, so neither lets the call through:
+ * a throw returns no `Decision`, so there is nothing for `assertAllowed` to pass and
+ * nothing is added to the K-34 `authorization` the operation's events carry. A
+ * caller that catches it and carries on has skipped a check, exactly as one that
+ * never called `ctx.check` has — no more than that. What differs is who is told. A
+ * denial is a statement about a principal ("was refused X"), and X here is not a
+ * permission; recording it fills the denial log with rows that read as an
+ * authorization problem, and on the system-actor path a denial is not even an
+ * available answer. It is a bug in the module, so it is `internal` — a 500 whose
+ * `detail` never leaves the server — and the message names the key for the log.
+ */
+import { permissionKey, substratError } from '@substrat-run/contracts';
+export function assertPermissionKey(permission) {
+    const parsed = permissionKey.safeParse(permission);
+    if (parsed.success)
+        return parsed.data;
+    throw substratError('internal', `ctx.check was handed ${JSON.stringify(permission)}, which is not a permission key ` +
+        `(${parsed.error.issues.map((i) => i.message).join('; ')}) — a bug in the calling ` +
+        'module, not a refusal: nothing was checked and no denial was recorded');
+}
+//# sourceMappingURL=check-key.js.map

package/dist/check-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-key.js","sourceRoot":"","sources":["../src/check-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAsB,MAAM,yBAAyB,CAAC;AAE3F,MAAM,UAAU,mBAAmB,CAAC,UAAmB;IACrD,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACvC,MAAM,aAAa,CACjB,UAAU,EACV,wBAAwB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,kCAAkC;QAClF,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B;QACnF,uEAAuE,CAC1E,CAAC;AACJ,CAAC"}