@substrat-run/kernel 0.147.0 → 0.148.0

package/dist/store-kind-releases.js

@@ -0,0 +1,252 @@
+/**
+ * A store kind's releases, its rollouts and the holds that serialize them (D-63, #2300), shared by
+ * both adapters' directories.
+ *
+ * - `store_kind_releases`: a release's bytes were stored (the bytes themselves live outside the
+ *   directory, keyed by kind and sha256). Insert-only: who uploaded a release, and from which
+ *   commit, is never rewritten.
+ * - `store_kind_rollouts`: one row per attempt to move every script of the kind to a release, in
+ *   `seq` order. A row is `rolling` until its holder ends it `good`, `failed` or `diverged`.
+ * - `store_kind_current`: the release the last `good` rollout moved every script to.
+ *
+ * "The immediately previous good release" (D-63) is recorded, never derived from an ordering:
+ * each rollout row names `previous_good_sha256`, the release a rollback from it returns to. A
+ * rollout of T from current F records F; a rollback goes to the current row's previous good X, and
+ * records X's own previous good, so after r1 → r2 → r3 one rollback reaches r2 and the next r1.
+ *
+ * A hold is a lease: `exclusive` for a rollout or a rollback, `shared` for a push or serve that
+ * rebuilds a script at the release it runs, which a rollout must not interleave with (a rebuild
+ * that read the old release and uploaded after the rollout moved the script would revert it).
+ * A begin or finish is refused unless the caller still holds the kind exclusively, so a holder
+ * whose lease lapsed cannot write over the next one; its `rolling` row reads as `diverged` to the
+ * next rollout, which converges every script again.
+ */
+import { substratError } from '@substrat-run/contracts';
+/** Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees one spelling on each side. */
+export const STORE_KIND_RELEASES_DDL = `
+  CREATE TABLE IF NOT EXISTS store_kind_releases (
+    kind          TEXT NOT NULL,
+    sha256        TEXT NOT NULL,
+    source_commit TEXT NOT NULL,
+    uploaded_by   TEXT NOT NULL,
+    uploaded_at   TEXT NOT NULL,
+    PRIMARY KEY (kind, sha256)
+  );
+  CREATE TABLE IF NOT EXISTS store_kind_rollouts (
+    kind                 TEXT NOT NULL,
+    seq                  INTEGER NOT NULL,
+    sha256               TEXT NOT NULL,
+    action               TEXT NOT NULL,
+    from_sha256          TEXT,
+    previous_good_sha256 TEXT,
+    state                TEXT NOT NULL,
+    actor                TEXT NOT NULL,
+    -- The hold the rollout runs under: a rolling row whose holder holds nothing has stopped.
+    holder               TEXT NOT NULL,
+    started_at           TEXT NOT NULL,
+    ended_at             TEXT,
+    detail               TEXT,
+    PRIMARY KEY (kind, seq)
+  );
+  CREATE TABLE IF NOT EXISTS store_kind_current (
+    kind   TEXT PRIMARY KEY,
+    sha256 TEXT NOT NULL,
+    seq    INTEGER NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS store_kind_holds (
+    kind       TEXT NOT NULL,
+    holder     TEXT NOT NULL,
+    mode       TEXT NOT NULL,
+    expires_at INTEGER NOT NULL,
+    PRIMARY KEY (kind, holder)
+  );
+`;
+const rolloutOf = (r) => ({
+    kind: r.kind,
+    seq: Number(r.seq),
+    sha256: r.sha256,
+    action: r.action,
+    fromSha256: r.from_sha256,
+    previousGoodSha256: r.previous_good_sha256,
+    state: r.state,
+    actor: r.actor,
+    startedAt: r.started_at,
+    endedAt: r.ended_at,
+    detail: r.detail,
+});
+const ROLLOUT_COLUMNS = 'kind, seq, sha256, action, from_sha256, previous_good_sha256, state, actor, started_at, ended_at, detail';
+function rolloutAt(db, kind, seq) {
+    const [row] = db.all(`SELECT ${ROLLOUT_COLUMNS} FROM store_kind_rollouts WHERE kind = ? AND seq = ?`, kind, seq);
+    return row ? rolloutOf(row) : undefined;
+}
+/** A stored release, or undefined. */
+export function storeKindReleaseIn(db, kind, sha256) {
+    const [row] = db.all('SELECT kind, sha256, source_commit, uploaded_by, uploaded_at FROM store_kind_releases WHERE kind = ? AND sha256 = ?', kind, sha256);
+    return row
+        ? { kind: row.kind, sha256: row.sha256, sourceCommit: row.source_commit, uploadedBy: row.uploaded_by, uploadedAt: row.uploaded_at }
+        : undefined;
+}
+/**
+ * Record that a release's bytes are stored. The same sha256 again is the same release, and the
+ * row already written is returned as it stands (`created: false`). The same sha256 from another
+ * commit is refused (`conflict`): one bundle has one source the reviewer reads.
+ */
+export function recordStoreKindReleaseIn(db, input) {
+    const held = storeKindReleaseIn(db, input.kind, input.sha256);
+    if (held) {
+        if (held.sourceCommit !== input.sourceCommit) {
+            throw substratError('conflict', `release ${input.sha256} of '${input.kind}' is stored as built from ${held.sourceCommit}, not ${input.sourceCommit}`);
+        }
+        return { record: held, created: false };
+    }
+    db.run('INSERT INTO store_kind_releases (kind, sha256, source_commit, uploaded_by, uploaded_at) VALUES (?, ?, ?, ?, ?)', input.kind, input.sha256, input.sourceCommit, input.actor, input.at);
+    return { record: storeKindReleaseIn(db, input.kind, input.sha256), created: true };
+}
+/**
+ * The kind's current release, every rollout, and where a rollback goes now.
+ *
+ * With `nowMs`, a `rolling` row whose holder no longer holds the kind exclusively is reported as
+ * `diverged` (read-time only, nothing is written): its holder stopped, and its scripts may be on
+ * either release. The next rollout's begin writes that state.
+ *
+ * `rollbackTarget` is, in order:
+ * - the target of a rollback that is the newest attempt since the current release, a `failed` one
+ *   aside, and ended `paused` or `diverged` (`unfinishedRollback`): posting the rollback again
+ *   continues it, and never turns it around onto the release it is leaving. A failed attempt moved
+ *   nothing, or returned what it moved, so it changes nothing here. No rollout may begin while a
+ *   rollback to an earlier release is unfinished, `paused` or `diverged` (`beginStoreKindRolloutIn`):
+ *   it is finished first, by posting it again. A rollback onto the current release (undoing a
+ *   diverged rollout) does not block a rollout. A rollback to an earlier release cannot meet the
+ *   schema rule (the route refuses one below the current schema), but one onto the current release
+ *   can, and then it never finishes, so going forward must stay open;
+ * - the current release itself, when a rollout since it ended `diverged` or `paused`: the fleet may
+ *   be mixed, and undoing that rollout means converging every script back on the release it was
+ *   healthy on, never going past it;
+ * - otherwise the immediately previous good release.
+ * An unfinished attempt never changes what "previous good" means.
+ */
+export function storeKindStateIn(db, kind, nowMs) {
+    const live = nowMs === undefined
+        ? undefined
+        : new Set(db.all("SELECT holder FROM store_kind_holds WHERE kind = ? AND mode = 'exclusive' AND expires_at > ?", kind, nowMs).map((h) => h.holder));
+    const rows = db.all(`SELECT ${ROLLOUT_COLUMNS}, holder FROM store_kind_rollouts WHERE kind = ? ORDER BY seq`, kind);
+    const rollouts = rows.map((r) => live && r.state === 'rolling' && !(r.holder && live.has(r.holder))
+        ? rolloutOf({ ...r, state: 'diverged', detail: 'its holder no longer holds the kind; the rollout stopped before it ended' })
+        : rolloutOf(r));
+    const [current] = db.all('SELECT sha256, seq FROM store_kind_current WHERE kind = ?', kind);
+    if (!current)
+        return { current: null, rollouts, rollbackTarget: null, unfinishedRollback: null };
+    const seq = Number(current.seq);
+    const row = rollouts.find((r) => r.seq === seq);
+    const previousGoodSha256 = row?.previousGoodSha256 ?? null;
+    const since = rollouts.filter((r) => r.seq > seq);
+    // A failed attempt moved nothing, or returned what it moved, so it never decides what comes next.
+    const newest = since.filter((r) => r.state !== 'failed').at(-1);
+    const unfinishedRollback = newest?.action === 'rollback' && (newest.state === 'paused' || newest.state === 'diverged') ? newest.sha256 : null;
+    const mixed = since.some((r) => r.state === 'diverged' || r.state === 'paused');
+    return {
+        current: { sha256: current.sha256, seq, previousGoodSha256 },
+        rollouts,
+        rollbackTarget: unfinishedRollback ?? (mixed ? current.sha256 : previousGoodSha256),
+        unfinishedRollback,
+    };
+}
+/**
+ * Take, or renew, a hold on a kind. Answers false when another holder's live hold excludes it: an
+ * exclusive one for any request, or any one for an exclusive request. A lapsed hold is dropped
+ * first. Asking in the other mode than the one held is refused.
+ *
+ * `renew` only extends a hold the holder still holds: a holder whose lease lapsed gets false, even
+ * when nobody took the kind since, because a lapsed holder cannot know what happened meanwhile.
+ * With `rolloutSeq` it also answers false unless that rollout is still `rolling`, so a rollout
+ * whose row another holder ended stops instead of moving scripts the state no longer describes.
+ */
+export function holdStoreKindIn(db, input) {
+    if (!(input.ttlMs > 0))
+        throw substratError('validation_failed', 'a store-kind hold needs a positive lifetime');
+    db.run('DELETE FROM store_kind_holds WHERE kind = ? AND expires_at <= ?', input.kind, input.nowMs);
+    const live = db.all('SELECT holder, mode FROM store_kind_holds WHERE kind = ?', input.kind);
+    const own = live.find((h) => h.holder === input.holder);
+    if (own && own.mode !== input.mode) {
+        throw substratError('conflict', `holder ${input.holder} holds '${input.kind}' ${own.mode}, not ${input.mode}`);
+    }
+    if ((input.renew || input.rolloutSeq !== undefined) && !own)
+        return false;
+    if (input.rolloutSeq !== undefined && rolloutAt(db, input.kind, input.rolloutSeq)?.state !== 'rolling')
+        return false;
+    const others = live.filter((h) => h.holder !== input.holder);
+    if (input.mode === 'exclusive' ? others.length > 0 : others.some((h) => h.mode === 'exclusive'))
+        return false;
+    db.run(`INSERT INTO store_kind_holds (kind, holder, mode, expires_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT (kind, holder) DO UPDATE SET expires_at = excluded.expires_at`, input.kind, input.holder, input.mode, input.nowMs + input.ttlMs);
+    return true;
+}
+/** Drop a hold. Dropping one already gone is not an error. */
+export function releaseStoreKindHoldIn(db, input) {
+    db.run('DELETE FROM store_kind_holds WHERE kind = ? AND holder = ?', input.kind, input.holder);
+}
+function assertExclusive(db, kind, holder, nowMs) {
+    const [row] = db.all("SELECT 1 AS held FROM store_kind_holds WHERE kind = ? AND holder = ? AND mode = 'exclusive' AND expires_at > ?", kind, holder, nowMs);
+    if (!row)
+        throw substratError('conflict', `'${kind}' is not held exclusively by ${holder}`);
+}
+/**
+ * Begin a rollout or a rollback of a stored release, as the exclusive holder. A rollout left
+ * `rolling` by an earlier holder ends `diverged` here: its scripts may be on either release, and
+ * this rollout reaches all of them. A rollback must name the current release's previous good one.
+ */
+export function beginStoreKindRolloutIn(db, input) {
+    assertExclusive(db, input.kind, input.holder, input.nowMs);
+    if (!storeKindReleaseIn(db, input.kind, input.sha256)) {
+        throw substratError('not_found', `release ${input.sha256} of '${input.kind}' is not stored`);
+    }
+    db.run(`UPDATE store_kind_rollouts SET state = 'diverged', ended_at = ?, detail = 'its holder stopped before the rollout ended'
+     WHERE kind = ? AND state = 'rolling'`, input.at, input.kind);
+    const { current, rollbackTarget, unfinishedRollback } = storeKindStateIn(db, input.kind, input.nowMs);
+    // A rollback under way to an earlier release blocks every rollout until it ends good. One onto
+    // the current release (undoing a diverged rollout) does not: if a script refuses to go below its
+    // schema, that rollback can never finish, and going forward is the way out.
+    if (input.action === 'rollout' && unfinishedRollback && unfinishedRollback !== current?.sha256) {
+        throw substratError('conflict', `a rollback of '${input.kind}' to ${unfinishedRollback} is part way through; post the rollback again to finish it before any rollout`);
+    }
+    let previousGood;
+    if (input.action === 'rollback') {
+        if (!current || !rollbackTarget)
+            throw substratError('conflict', `'${input.kind}' has no previous good release to roll back to`);
+        if (rollbackTarget !== input.sha256) {
+            throw substratError('conflict', `a rollback of '${input.kind}' returns to ${rollbackTarget}, not ${input.sha256}`);
+        }
+        if (input.sha256 === current.sha256) {
+            // Undoing a diverged rollout: back onto the current release, whose previous good stays.
+            previousGood = current.previousGoodSha256;
+        }
+        else {
+            const [made] = db.all(`SELECT previous_good_sha256 FROM store_kind_rollouts
+         WHERE kind = ? AND sha256 = ? AND state = 'good' ORDER BY seq DESC LIMIT 1`, input.kind, input.sha256);
+            previousGood = made?.previous_good_sha256 ?? null;
+        }
+    }
+    else {
+        // Rolling out the current release again (a resume) keeps where a rollback from it returns to.
+        previousGood = current ? (current.sha256 === input.sha256 ? current.previousGoodSha256 : current.sha256) : null;
+    }
+    const next = Number(db.all('SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM store_kind_rollouts WHERE kind = ?', input.kind)[0].next);
+    db.run(`INSERT INTO store_kind_rollouts (${ROLLOUT_COLUMNS}, holder) VALUES (?, ?, ?, ?, ?, ?, 'rolling', ?, ?, NULL, NULL, ?)`, input.kind, next, input.sha256, input.action, current?.sha256 ?? null, previousGood, input.actor, input.at, input.holder);
+    return rolloutAt(db, input.kind, next);
+}
+/** End a rollout the caller began, as the exclusive holder. A good one makes its release current. */
+export function finishStoreKindRolloutIn(db, input) {
+    assertExclusive(db, input.kind, input.holder, input.nowMs);
+    const row = rolloutAt(db, input.kind, input.seq);
+    if (!row)
+        throw substratError('not_found', `'${input.kind}' has no rollout ${input.seq}`);
+    if (row.state !== 'rolling')
+        throw substratError('conflict', `rollout ${input.seq} of '${input.kind}' already ended ${row.state}`);
+    db.run('UPDATE store_kind_rollouts SET state = ?, ended_at = ?, detail = ? WHERE kind = ? AND seq = ?', input.state, input.at, input.detail, input.kind, input.seq);
+    if (input.state === 'good') {
+        db.run(`INSERT INTO store_kind_current (kind, sha256, seq) VALUES (?, ?, ?)
+       ON CONFLICT (kind) DO UPDATE SET sha256 = excluded.sha256, seq = excluded.seq`, input.kind, row.sha256, input.seq);
+    }
+    return rolloutAt(db, input.kind, input.seq);
+}
+//# sourceMappingURL=store-kind-releases.js.map

package/dist/store-kind-releases.js.map

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

package/dist/upload-link.d.ts

@@ -0,0 +1,89 @@
+import { type AttachmentRecord, type CheckSubject, type Decision, type DomainEventInput, type EntityRef, type Instant, type MintedUploadLink, type PermissionKey, type PrincipalId, type UploadLinkMintInput, type UploadLinkPolicy, type UploadLinkRecord, type UploadLinkView } from '@substrat-run/contracts';
+import type { ScopedSql } from './scope-host.js';
+export declare const UPLOAD_LINK_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_upload_links (\n    id TEXT PRIMARY KEY,\n    -- SHA-256 hex of the secret. The secret itself is stored NOWHERE.\n    token_hash TEXT NOT NULL UNIQUE,\n    entity_type TEXT NOT NULL,\n    entity_id TEXT NOT NULL,\n    -- NULL = the uploader names the file.\n    filename TEXT,\n    max_bytes INTEGER NOT NULL,\n    -- JSON array of media types / families, or NULL = any type.\n    content_types TEXT,\n    visibility TEXT NOT NULL,\n    -- The principal the attachment is written AS: its author, and whose `writePermission`\n    -- is checked again at redemption.\n    minted_by TEXT NOT NULL,\n    minted_at TEXT NOT NULL,\n    expires_at TEXT NOT NULL,\n    redeemed_at TEXT,\n    -- The attachment this link produced.\n    attachment_id TEXT,\n    -- Tombstone, never a delete: a link that was minted is evidence of why a file arrived.\n    revoked_at TEXT,\n    revoked_by TEXT\n  );\n  CREATE INDEX IF NOT EXISTS _substrat_upload_links_entity\n    ON _substrat_upload_links (entity_type, entity_id);\n";
+/** The tables `UPLOAD_LINK_DDL` builds — what a copy of a scope leaves behind. */
+export declare const UPLOAD_LINK_TABLE_NAMES: readonly ['_substrat_upload_links'];
+/** `reason` slugs a redemption refuses with, so the HTTP route can answer 410/413/415 and a client can act. */
+export declare const UPLOAD_LINK_GONE = "upload_link_gone";
+export declare const UPLOAD_LINK_TOO_LARGE = "upload_link_too_large";
+export declare const UPLOAD_LINK_TYPE_REFUSED = "upload_link_type_refused";
+export declare const UPLOAD_LINK_WRONG_TARGET = "upload_link_wrong_target";
+/** A fresh link secret: 256 bits, base64url, prefixed. Only its hash is ever stored. */
+export declare function mintUploadLinkSecret(): string;
+/** Is `type` (already stripped of parameters, lowercase) admitted by `allowed`? `null` admits anything. */
+export declare function uploadContentTypeAllowed(allowed: readonly string[] | null, type: string): boolean;
+/** What an operation handler sees as `ctx.attachments`. */
+export interface AttachmentVerbs {
+    /**
+     * Mint a single-use URL that lets its holder upload ONE file to `entity` — and return the
+     * secret and the path that carries it, once.
+     *
+     * The target must declare `uploadLinks` in its `attachmentTargets` entry, and the caller
+     * must hold the target's `writePermission` on the entity (the check an upload makes);
+     * it is made again, as the same principal, when the link is redeemed. Only a principal may
+     * mint. The operation's own guards — an entity lock, a state check — run in the operation,
+     * before this; they are not re-run at redemption, so keep `ttlSeconds` short.
+     *
+     * ```ts
+     * assertAllowed(await ctx.check('contract:write', ref));
+     * const link = await ctx.attachments.mintUploadUrl({ entity: ref, filename: 'signed.pdf' });
+     * return { url: `${origin}${link.path}`, expiresAt: link.expiresAt };
+     * ```
+     *
+     * The same tripwire `ctx.capabilities.mint` has applies: while this invocation runs,
+     * `ctx.emit` and `ctx.sql` refuse a record carrying the secret verbatim. Transactional with
+     * the operation: a mint whose operation throws never happened.
+     */
+    mintUploadUrl(input: UploadLinkMintInput): Promise<MintedUploadLink>;
+    /** Revoke a link that has not been redeemed. Allowed to anyone who could have minted it. Idempotent. */
+    revokeUploadLink(id: string): Promise<void>;
+    /** This scope's upload links, newest first — never the secret. What a follow-up operation reads to find the attachment a link produced. */
+    uploadLinks(filter?: {
+        entity?: EntityRef;
+        limit?: number;
+    }): UploadLinkRecord[];
+}
+/** What the verbs need of the target's declaration: its write key and its link policy. */
+export interface UploadTarget {
+    write: PermissionKey;
+    uploadLinks?: UploadLinkPolicy;
+}
+export interface AttachmentVerbDeps {
+    /** RAW spine access inside the operation's own transaction. */
+    sql: ScopedSql;
+    subject: CheckSubject;
+    now: Instant;
+    /** The operation's OWN check. */
+    check: (permission: PermissionKey, entity?: EntityRef) => Promise<Decision>;
+    emit: (event: DomainEventInput) => void;
+    assertWrites: (verb: string) => void;
+    /** This invocation's minted secrets — appended to by `mint`, read by the secret guards. */
+    minted: string[];
+    /** The declared attachment target for an entity type, if any module declares one. */
+    targetOf: (entityType: string) => UploadTarget | undefined;
+}
+export declare function createAttachmentVerbs(deps: AttachmentVerbDeps): AttachmentVerbs;
+/** What the route needs before it reads a byte, and who the write is made as. */
+export interface UploadLinkInspection {
+    view: UploadLinkView;
+    mintedBy: PrincipalId;
+}
+/**
+ * Look a secret up without spending it: `not_found` for one that names nothing, `conflict`
+ * with reason `upload_link_gone` for one that is used, expired or revoked.
+ */
+export declare function inspectUploadLink(deps: {
+    sql: ScopedSql;
+    now: Instant;
+}, secret: unknown): Promise<UploadLinkInspection>;
+/**
+ * Spend the link for `record`, INSIDE the transaction that inserts the attachment row — so a
+ * refusal anywhere rolls the spend back. Judges the record against the link, never the other
+ * way round: the target, the author, the size and the type are all the link's to refuse.
+ */
+export declare function redeemUploadLinkInTransaction(deps: {
+    sql: ScopedSql;
+    now: Instant;
+    emit: (event: DomainEventInput) => void;
+}, secret: unknown, record: AttachmentRecord): Promise<void>;
+//# sourceMappingURL=upload-link.d.ts.map

package/dist/upload-link.d.ts.map

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

package/dist/upload-link.js

@@ -0,0 +1,277 @@
+import { ATTACHMENT_UPLOAD_LINK_MINTED, ATTACHMENT_UPLOAD_LINK_REDEEMED, ATTACHMENT_UPLOAD_LINK_REVOKED, UPLOAD_LINK_DEFAULT_TTL_SECONDS, UPLOAD_LINK_MAX_BYTES_CEILING, UPLOAD_LINK_SECRET_PREFIX, principalId as principalIdSchema, substratError, uploadLinkMintInput, uploadLinkPath, } from '@substrat-run/contracts';
+import { toBase64url } from './base64url.js';
+import { capabilityTokenHash } from './capability.js';
+import { assertAllowed } from './permission-checker.js';
+import { ulid } from './ulid.js';
+export const UPLOAD_LINK_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_upload_links (
+    id TEXT PRIMARY KEY,
+    -- SHA-256 hex of the secret. The secret itself is stored NOWHERE.
+    token_hash TEXT NOT NULL UNIQUE,
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    -- NULL = the uploader names the file.
+    filename TEXT,
+    max_bytes INTEGER NOT NULL,
+    -- JSON array of media types / families, or NULL = any type.
+    content_types TEXT,
+    visibility TEXT NOT NULL,
+    -- The principal the attachment is written AS: its author, and whose \`writePermission\`
+    -- is checked again at redemption.
+    minted_by TEXT NOT NULL,
+    minted_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    redeemed_at TEXT,
+    -- The attachment this link produced.
+    attachment_id TEXT,
+    -- Tombstone, never a delete: a link that was minted is evidence of why a file arrived.
+    revoked_at TEXT,
+    revoked_by TEXT
+  );
+  CREATE INDEX IF NOT EXISTS _substrat_upload_links_entity
+    ON _substrat_upload_links (entity_type, entity_id);
+`;
+/** The tables `UPLOAD_LINK_DDL` builds — what a copy of a scope leaves behind. */
+export const UPLOAD_LINK_TABLE_NAMES = ['_substrat_upload_links'];
+/** `reason` slugs a redemption refuses with, so the HTTP route can answer 410/413/415 and a client can act. */
+export const UPLOAD_LINK_GONE = 'upload_link_gone';
+export const UPLOAD_LINK_TOO_LARGE = 'upload_link_too_large';
+export const UPLOAD_LINK_TYPE_REFUSED = 'upload_link_type_refused';
+export const UPLOAD_LINK_WRONG_TARGET = 'upload_link_wrong_target';
+const COLUMNS = 'id, entity_type, entity_id, filename, max_bytes, content_types, visibility, minted_by, minted_at, ' +
+    'expires_at, redeemed_at, attachment_id, revoked_at, revoked_by';
+/** A fresh link secret: 256 bits, base64url, prefixed. Only its hash is ever stored. */
+export function mintUploadLinkSecret() {
+    return UPLOAD_LINK_SECRET_PREFIX + toBase64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+/** A secret that cannot be one of ours is refused before it is hashed. */
+const plausibleSecret = (secret) => typeof secret === 'string' && secret.startsWith(UPLOAD_LINK_SECRET_PREFIX) && secret.length <= 128;
+/** Is `type` (already stripped of parameters, lowercase) admitted by `allowed`? `null` admits anything. */
+export function uploadContentTypeAllowed(allowed, type) {
+    if (allowed === null)
+        return true;
+    const t = type.toLowerCase();
+    return allowed.some((a) => (a.endsWith('/*') ? t.startsWith(a.slice(0, -1)) : a === t));
+}
+const stateOf = (row, now) => row.revoked_at !== null ? 'revoked' : row.redeemed_at !== null ? 'redeemed' : row.expires_at <= now ? 'expired' : 'pending';
+function recordOf(row, now) {
+    return {
+        id: row.id,
+        entity: { entityType: row.entity_type, entityId: row.entity_id },
+        filename: row.filename,
+        maxBytes: row.max_bytes,
+        contentTypes: row.content_types === null ? null : JSON.parse(row.content_types),
+        visibility: row.visibility,
+        mintedBy: principalIdSchema.parse(row.minted_by),
+        mintedAt: row.minted_at,
+        expiresAt: row.expires_at,
+        state: stateOf(row, now),
+        redeemedAt: row.redeemed_at,
+        attachmentId: row.attachment_id,
+    };
+}
+const MS_PER_SECOND = 1000;
+function principalOf(subject, verb) {
+    if (subject.kind !== 'principal') {
+        throw substratError('forbidden', `${verb}: only a principal may mint or revoke an upload link — a ${subject.kind} actor has no ` +
+            'authorship to lend an attachment', { reason: 'upload_link_delegation' });
+    }
+    return subject.id;
+}
+export function createAttachmentVerbs(deps) {
+    const readRow = (id) => deps.sql.query(`SELECT ${COLUMNS} FROM _substrat_upload_links WHERE id = ?`, [id])[0];
+    return {
+        async mintUploadUrl(raw) {
+            deps.assertWrites('ctx.attachments.mintUploadUrl');
+            const minter = principalOf(deps.subject, 'ctx.attachments.mintUploadUrl');
+            const input = uploadLinkMintInput.parse(raw);
+            const target = deps.targetOf(input.entity.entityType);
+            if (!target) {
+                throw substratError('validation_failed', `ctx.attachments.mintUploadUrl: '${input.entity.entityType}' is not a declared attachment target`);
+            }
+            const policy = target.uploadLinks;
+            if (!policy) {
+                throw substratError('forbidden', `ctx.attachments.mintUploadUrl: '${input.entity.entityType}' does not declare uploadLinks in its attachmentTargets entry`, { reason: 'upload_links_not_declared' });
+            }
+            const maxBytes = input.maxBytes ?? policy.maxBytes;
+            if (maxBytes > policy.maxBytes || maxBytes > UPLOAD_LINK_MAX_BYTES_CEILING) {
+                throw substratError('validation_failed', `ctx.attachments.mintUploadUrl: maxBytes ${maxBytes} is above the target's ${policy.maxBytes} — a link narrows its target's policy, never widens it`);
+            }
+            // Delegation, never elevation: the key an upload checks, on the entity, as the caller.
+            assertAllowed(await deps.check(target.write, input.entity));
+            const id = ulid();
+            const secret = mintUploadLinkSecret();
+            const expiresAt = new Date(Date.parse(deps.now) + (input.ttlSeconds ?? UPLOAD_LINK_DEFAULT_TTL_SECONDS) * MS_PER_SECOND).toISOString();
+            const visibility = input.visibility ?? 'internal';
+            const contentTypes = policy.contentTypes ?? null;
+            deps.sql.exec(`INSERT INTO _substrat_upload_links
+           (id, token_hash, entity_type, entity_id, filename, max_bytes, content_types, visibility,
+            minted_by, minted_at, expires_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                id,
+                await capabilityTokenHash(secret),
+                input.entity.entityType,
+                input.entity.entityId,
+                input.filename ?? null,
+                maxBytes,
+                contentTypes === null ? null : JSON.stringify(contentTypes),
+                visibility,
+                minter,
+                deps.now,
+                expiresAt,
+            ]);
+            deps.minted.push(secret);
+            const payload = {
+                linkId: id,
+                entity: input.entity,
+                filename: input.filename ?? null,
+                maxBytes,
+                contentTypes,
+                visibility,
+                expiresAt,
+                mintedBy: minter,
+            };
+            deps.emit({
+                type: ATTACHMENT_UPLOAD_LINK_MINTED,
+                schemaVersion: 1,
+                entity: input.entity,
+                piiClass: 'none',
+                payload,
+            });
+            return {
+                id,
+                secret,
+                path: uploadLinkPath(input.entity, secret),
+                expiresAt,
+                maxBytes,
+                filename: input.filename ?? null,
+            };
+        },
+        async revokeUploadLink(id) {
+            deps.assertWrites('ctx.attachments.revokeUploadLink');
+            const revoker = principalOf(deps.subject, 'ctx.attachments.revokeUploadLink');
+            const row = readRow(id);
+            if (!row)
+                throw substratError('not_found', `no upload link ${id} in this scope`);
+            const entity = { entityType: row.entity_type, entityId: row.entity_id };
+            const target = deps.targetOf(row.entity_type);
+            if (target)
+                assertAllowed(await deps.check(target.write, entity));
+            // A spent or already-revoked link has nothing left to take back.
+            if (row.revoked_at !== null || row.redeemed_at !== null)
+                return;
+            deps.sql.exec(`UPDATE _substrat_upload_links SET revoked_at = ?, revoked_by = ? WHERE id = ?`, [
+                deps.now,
+                revoker,
+                id,
+            ]);
+            const payload = { linkId: id, entity, revokedBy: revoker };
+            deps.emit({
+                type: ATTACHMENT_UPLOAD_LINK_REVOKED,
+                schemaVersion: 1,
+                entity,
+                piiClass: 'none',
+                payload,
+            });
+        },
+        uploadLinks(filter) {
+            const params = [];
+            let where = '';
+            if (filter?.entity) {
+                where = 'WHERE entity_type = ? AND entity_id = ?';
+                params.push(filter.entity.entityType, filter.entity.entityId);
+            }
+            const limit = Math.min(Math.max(Math.trunc(filter?.limit ?? 50), 1), 200);
+            params.push(limit);
+            return deps.sql
+                .query(`SELECT ${COLUMNS} FROM _substrat_upload_links ${where} ORDER BY id DESC LIMIT ?`, params)
+                .map((r) => recordOf(r, deps.now));
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Redemption — the host's half. A secret in, an attachment out.
+// ---------------------------------------------------------------------------
+/** One answer for every secret that is not ours or names nothing, so a probe learns nothing it can act on. */
+const unknownLink = () => substratError('not_found', 'This upload link is not valid.');
+/** The 410: it was ours, and it is spent, expired or revoked. Said only to a holder of the secret. */
+const goneLink = () => substratError('conflict', 'This upload link has been used, has expired or was revoked.', { reason: UPLOAD_LINK_GONE });
+async function liveRow(sql, now, secret) {
+    if (!plausibleSecret(secret))
+        throw unknownLink();
+    const row = sql.query(`SELECT ${COLUMNS} FROM _substrat_upload_links WHERE token_hash = ?`, [await capabilityTokenHash(secret)])[0];
+    if (!row)
+        throw unknownLink();
+    if (stateOf(row, now) !== 'pending')
+        throw goneLink();
+    return row;
+}
+/**
+ * Look a secret up without spending it: `not_found` for one that names nothing, `conflict`
+ * with reason `upload_link_gone` for one that is used, expired or revoked.
+ */
+export async function inspectUploadLink(deps, secret) {
+    const row = await liveRow(deps.sql, deps.now, secret);
+    const r = recordOf(row, deps.now);
+    return {
+        view: {
+            entity: r.entity,
+            filename: r.filename,
+            maxBytes: r.maxBytes,
+            contentTypes: r.contentTypes,
+            visibility: r.visibility,
+        },
+        mintedBy: r.mintedBy,
+    };
+}
+/**
+ * Spend the link for `record`, INSIDE the transaction that inserts the attachment row — so a
+ * refusal anywhere rolls the spend back. Judges the record against the link, never the other
+ * way round: the target, the author, the size and the type are all the link's to refuse.
+ */
+export async function redeemUploadLinkInTransaction(deps, secret, record) {
+    const row = await liveRow(deps.sql, deps.now, secret);
+    if (row.entity_type !== record.entity.entityType || row.entity_id !== record.entity.entityId) {
+        // The path named another entity than the link was minted for: nothing is spent.
+        throw substratError('not_found', 'This upload link is not valid for that target.', {
+            reason: UPLOAD_LINK_WRONG_TARGET,
+        });
+    }
+    if (record.createdBy !== row.minted_by) {
+        throw substratError('internal', 'an upload link was redeemed as someone other than its minter');
+    }
+    if (record.size > row.max_bytes) {
+        throw substratError('validation_failed', `The file is ${record.size} bytes; this link admits at most ${row.max_bytes}.`, {
+            reason: UPLOAD_LINK_TOO_LARGE,
+        });
+    }
+    const allowed = row.content_types === null ? null : JSON.parse(row.content_types);
+    if (!uploadContentTypeAllowed(allowed, record.contentType)) {
+        throw substratError('validation_failed', `A file of type ${record.contentType} is not admitted by this link.`, {
+            reason: UPLOAD_LINK_TYPE_REFUSED,
+        });
+    }
+    if (row.filename !== null && record.filename !== row.filename) {
+        throw substratError('internal', 'an upload link with a fixed file name was redeemed under another');
+    }
+    const spent = deps.sql.exec(`UPDATE _substrat_upload_links SET redeemed_at = ?, attachment_id = ?
+     WHERE id = ? AND redeemed_at IS NULL AND revoked_at IS NULL`, [deps.now, record.id, row.id]);
+    if (spent.changes !== 1)
+        throw goneLink();
+    const payload = {
+        linkId: row.id,
+        entity: record.entity,
+        attachmentId: record.id,
+        size: record.size,
+        sha256: record.sha256,
+        mintedBy: principalIdSchema.parse(row.minted_by),
+    };
+    deps.emit({
+        type: ATTACHMENT_UPLOAD_LINK_REDEEMED,
+        schemaVersion: 1,
+        entity: record.entity,
+        piiClass: 'none',
+        payload,
+    });
+}
+//# sourceMappingURL=upload-link.js.map