gazetta 0.7.0 → 0.8.0

package/dist/admin-api/middleware/capability.js

@@ -0,0 +1,65 @@
+/**
+ * Capability-check middleware — gates a route on the principal's
+ * having a specific capability.
+ *
+ * # Per-route opt-in
+ *
+ * Routes call `requireCapability('read:pages')` to attach a check
+ * to a specific endpoint. The check runs after `principalMiddleware`
+ * (so `c.var.principal` is populated). Anonymous principals (id
+ * `'unknown'`) fail capability checks because their capability set
+ * is empty — translates to 401 (not 403; per design-auth-rbac.md
+ * the principal isn't authenticated yet).
+ *
+ * # Failure modes
+ *
+ *   - Principal is anonymous (no upstream auth) → 401 with
+ *     WWW-Authenticate (matches the principal middleware's 401)
+ *   - Principal is authenticated but lacks the capability → 403
+ *     with structured body listing the missing capability and the
+ *     principal's role
+ *
+ * # Composition
+ *
+ * Routes can wire multiple capability checks (e.g., a route that
+ * needs both `read:pages` and `edit:pages` in different code paths
+ * — the broader read check at the route level, narrower edit check
+ * gating a specific operation). v1 ships single-capability gates;
+ * multi-capability composition is left to the consumer.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: authorization gate only. Doesn't extract identity (Cut
+ *     7's principalMiddleware does that), doesn't audit (Cut 5 of
+ *     audit foundation does).
+ *   - DIP: depends on `capabilityGrants` pure function, not on
+ *     the principal middleware's internals.
+ */
+import { createMiddleware } from 'hono/factory';
+import { capabilityGrants, UNKNOWN_ACTOR_ID } from '../../auth/index.js';
+/**
+ * Build a middleware that requires the specified capability.
+ * Returns 401 for anonymous requests, 403 for authenticated
+ * requests lacking the capability.
+ */
+export function requireCapability(capability) {
+    return createMiddleware(async (c, next) => {
+        const principal = c.get('principal');
+        // Anonymous principal — no upstream identity. Translate to
+        // 401 (not 403); the request hasn't authenticated yet.
+        if (principal.id === UNKNOWN_ACTOR_ID && principal.role === 'unknown') {
+            return c.json({ code: 'UNAUTHENTICATED', error: `This endpoint requires capability "${capability}"` }, 401, { 'WWW-Authenticate': 'Bearer realm="gazetta-admin"' });
+        }
+        // Authenticated principal — capability check.
+        if (!capabilityGrants(principal.capabilities, capability)) {
+            return c.json({
+                code: 'FORBIDDEN',
+                missing: [capability],
+                role: principal.role,
+                error: `Role "${principal.role}" does not have capability "${capability}"`,
+            }, 403);
+        }
+        await next();
+    });
+}
+//# sourceMappingURL=capability.js.map

package/dist/admin-api/middleware/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/admin-api/middleware/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAGxE;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,OAAO,gBAAgB,CAAe,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACtD,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QACpC,2DAA2D;QAC3D,uDAAuD;QACvD,IAAI,SAAS,CAAC,EAAE,KAAK,gBAAgB,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACtE,OAAO,CAAC,CAAC,IAAI,CACX,EAAE,IAAI,EAAE,iBAA0B,EAAE,KAAK,EAAE,sCAAsC,UAAU,GAAG,EAAE,EAChG,GAAG,EACH,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,CACvD,CAAA;QACH,CAAC;QACD,8CAA8C;QAC9C,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,YAAY,EAAE,UAAU,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,CAAC,IAAI,CACX;gBACE,IAAI,EAAE,WAAoB;gBAC1B,OAAO,EAAE,CAAC,UAAU,CAAC;gBACrB,IAAI,EAAE,SAAS,CAAC,IAAI;gBACpB,KAAK,EAAE,SAAS,SAAS,CAAC,IAAI,+BAA+B,UAAU,GAAG;aAC3E,EACD,GAAG,CACJ,CAAA;QACH,CAAC;QACD,MAAM,IAAI,EAAE,CAAA;IACd,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/admin-api/middleware/principal.d.ts

@@ -0,0 +1,18 @@
+import { type AuthIdentityProvider, type Principal } from '../../auth/index.js';
+/**
+ * Hono context augmentation — readers see `c.var.principal` typed
+ * as `Principal` (always populated; never undefined after this
+ * middleware runs).
+ */
+export type PrincipalEnv = {
+    Variables: {
+        principal: Principal;
+    };
+};
+/**
+ * Build the principal middleware. Pass the configured provider OR
+ * omit to fall back to `none` mode. Production wiring resolves the
+ * provider from `site.config.ts admin.auth` at boot.
+ */
+export declare function principalMiddleware(provider?: AuthIdentityProvider): import("hono").MiddlewareHandler<PrincipalEnv, string, {}, Response>;
+//# sourceMappingURL=principal.d.ts.map

package/dist/admin-api/middleware/principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../../../src/admin-api/middleware/principal.ts"],"names":[],"mappings":"AAiDA,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,SAAS,EAGf,MAAM,qBAAqB,CAAA;AAE5B;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE;QACT,SAAS,EAAE,SAAS,CAAA;KACrB,CAAA;CACF,CAAA;AAkDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,oBAAuC,wEA0BpF"}

package/dist/admin-api/middleware/principal.js

@@ -0,0 +1,128 @@
+/**
+ * Principal middleware — wires the auth/RBAC layer (`packages/gazetta/src/auth/`)
+ * into the Hono request context.
+ *
+ * # What this middleware does
+ *
+ * 1. On boot, constructs the configured `AuthIdentityProvider` from
+ *    `admin.auth` in the loaded SiteManifest. Falls back to the
+ *    `none`-mode provider when `admin.auth` is absent.
+ * 2. On every request, calls `provider.extractPrincipal(req)` and
+ *    attaches the result to `c.var.principal`.
+ * 3. Anonymous requests (provider returns `null`) get a synthesized
+ *    Principal with `id: 'unknown'` + `role: 'unknown'` + empty
+ *    capabilities. The capability-check middleware (Cut 8) decides
+ *    whether to allow these (none-mode or public routes) or 401.
+ * 4. Provider throws (`AuthenticationError`) → 401 with the error
+ *    message; doesn't leak details about the underlying failure.
+ *
+ * # Capability population
+ *
+ * For `forwarded-user` and `cloudflare-access` providers (which can
+ * surface upstream group claims), this middleware would call
+ * `resolveRole({ groups, mapping, customRoles })` to expand the
+ * principal's capabilities. v1 wires the role-resolver in a
+ * follow-up cut once one of the providers actually exposes group
+ * claims through the AuthRequest shape — for now the providers
+ * return `capabilities: []` and the operator's role mapping config
+ * doesn't reach the resolver yet.
+ *
+ * # Why this is its own middleware (not folded into the existing one)
+ *
+ * The existing `authMiddleware` is a simple bearer-token guard for
+ * `GAZETTA_TOKEN` — orthogonal to upstream-identity extraction.
+ * They compose: bearer-token gates "is this request allowed to
+ * reach the admin API at all"; principal middleware identifies
+ * "who is the user behind this request." Most deployments use
+ * one or the other (bearer-token for solo / dev; principal for
+ * team CMS); some compose both (CI pipeline auth-token + upstream
+ * Cloudflare Access for human users).
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: extracts identity + attaches to context. Authorization
+ *     (capability checks) is Cut 8's middleware.
+ *   - DIP: depends on `AuthIdentityProvider` interface, not on
+ *     specific provider classes.
+ */
+import { createMiddleware } from 'hono/factory';
+import { AuthenticationError, noneAuthProvider, UNKNOWN_ACTOR_ID, } from '../../auth/index.js';
+/**
+ * The synthetic anonymous principal returned when no upstream
+ * identity is present. Surfaced as `id: 'unknown'`, `role:
+ * 'unknown'`, no capabilities — Cut 8's capability-check middleware
+ * 401s on any required capability.
+ */
+const ANONYMOUS_PRINCIPAL = {
+    id: UNKNOWN_ACTOR_ID,
+    role: 'unknown',
+    trustMode: 'none',
+    capabilities: [],
+};
+/**
+ * Adapt a Hono request into the `AuthRequest` shape the auth/
+ * providers expect. Headers come from Hono's case-insensitive
+ * lookup; we normalize to lowercase keys for provider consistency.
+ */
+function toAuthRequest(c) {
+    const headers = new Map();
+    // Hono exposes headers via c.req.header() (single value). The
+    // raw request headers are accessible via c.req.raw.headers
+    // which is a fetch-style Headers object.
+    const raw = c.req.raw.headers;
+    raw.forEach((value, key) => {
+        headers.set(key.toLowerCase(), value);
+    });
+    // Source IP — Hono doesn't expose this directly; honest extraction
+    // is per-platform (per design-audit.md's trust-mode-driven IP
+    // section). v1 reads from a CF-Connecting-IP / X-Forwarded-For
+    // best-effort; provider-specific extraction lands when the audit
+    // foundation's source-IP recording (Cut 4 of audit) ships.
+    const sourceIp = raw.get('cf-connecting-ip') ?? raw.get('x-real-ip') ?? extractFirstXffEntry(raw.get('x-forwarded-for'));
+    return {
+        headers,
+        sourceIp: sourceIp ?? undefined,
+        method: c.req.method,
+        url: c.req.url,
+    };
+}
+function extractFirstXffEntry(xff) {
+    if (!xff)
+        return null;
+    const first = xff.split(',')[0]?.trim();
+    return first || null;
+}
+/**
+ * Build the principal middleware. Pass the configured provider OR
+ * omit to fall back to `none` mode. Production wiring resolves the
+ * provider from `site.config.ts admin.auth` at boot.
+ */
+export function principalMiddleware(provider = noneAuthProvider) {
+    return createMiddleware(async (c, next) => {
+        let principal;
+        try {
+            principal = await provider.extractPrincipal(toAuthRequest(c));
+        }
+        catch (err) {
+            if (err instanceof AuthenticationError) {
+                // Surface as 401 with the error message. The provider's
+                // message is operator-facing diagnostic detail (e.g.,
+                // "JWT verification failed: signature invalid"); we surface
+                // it in a structured body. For external-facing 401s the
+                // middleware could mask the message, but this is admin-API
+                // only — operators benefit from the diagnostic context.
+                return c.json({ code: 'UNAUTHENTICATED', error: err.message }, 401, {
+                    'WWW-Authenticate': 'Bearer realm="gazetta-admin"',
+                });
+            }
+            // Unexpected (non-AuthenticationError) — let Hono's default
+            // error handler take over so the operator sees the stack.
+            throw err;
+        }
+        // Anonymous request — synthesize the unknown principal so
+        // downstream middleware always has a Principal to read.
+        c.set('principal', principal ?? ANONYMOUS_PRINCIPAL);
+        await next();
+    });
+}
+//# sourceMappingURL=principal.js.map

package/dist/admin-api/middleware/principal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.js","sourceRoot":"","sources":["../../../src/admin-api/middleware/principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C,OAAO,EACL,mBAAmB,EAInB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAa5B;;;;;GAKG;AACH,MAAM,mBAAmB,GAAc;IACrC,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,MAAM;IACjB,YAAY,EAAE,EAAE;CACjB,CAAA;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,CAAU;IAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IACzC,8DAA8D;IAC9D,2DAA2D;IAC3D,yCAAyC;IACzC,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAA;IAC7B,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACzB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAA;IACvC,CAAC,CAAC,CAAA;IACF,mEAAmE;IACnE,8DAA8D;IAC9D,+DAA+D;IAC/D,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,QAAQ,GACZ,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAA;IACzG,OAAO;QACL,OAAO;QACP,QAAQ,EAAE,QAAQ,IAAI,SAAS;QAC/B,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;QACpB,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG;KACf,CAAA;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAkB;IAC9C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IACrB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;IACvC,OAAO,KAAK,IAAI,IAAI,CAAA;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAiC,gBAAgB;IACnF,OAAO,gBAAgB,CAAe,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACtD,IAAI,SAA2B,CAAA;QAC/B,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,mBAAmB,EAAE,CAAC;gBACvC,wDAAwD;gBACxD,sDAAsD;gBACtD,4DAA4D;gBAC5D,wDAAwD;gBACxD,2DAA2D;gBAC3D,wDAAwD;gBACxD,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAA0B,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE;oBAC3E,kBAAkB,EAAE,8BAA8B;iBACnD,CAAC,CAAA;YACJ,CAAC;YACD,4DAA4D;YAC5D,0DAA0D;YAC1D,MAAM,GAAG,CAAA;QACX,CAAC;QACD,0DAA0D;QAC1D,wDAAwD;QACxD,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,IAAI,mBAAmB,CAAC,CAAA;QACpD,MAAM,IAAI,EAAE,CAAA;IACd,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/admin-api/routes/archive-review.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Cut 14 — review-workflow integration for archive lifecycle.
+ *
+ * Per `design-soft-delete.md` Q9 (N-A.2 + N-B.1):
+ *   - Archive on `pending-review` → auto-withdraw fires first; then archive.
+ *     Two audit events emitted: `review-withdraw` with
+ *     `metadata.autoWithdrawn: true`, then `archive`.
+ *   - Archive on `approved` → approved state discarded; no synthetic
+ *     withdraw event (the prior state is recorded in archive metadata
+ *     as `priorReviewState: 'approved'`).
+ *   - Archive on `draft` → no review-related side effects.
+ *   - Restore (unarchive) → always to `draft`, regardless of prior state.
+ *     Author re-submits if review needed. Auto-restoring to `approved`
+ *     would let stale content ship without re-validation.
+ *
+ * # Forward-compat with review-workflow's Tier-3 timeline
+ *
+ * The review-workflow foundation hasn't shipped. Today's manifests
+ * never carry a `reviewState` field; this module's logic is therefore
+ * a no-op on every current production save. When review-workflow Cut 6
+ * lands and starts writing `reviewState` to manifests, this module
+ * activates without code changes.
+ *
+ * Gate is data-driven (`manifest.reviewState` presence), not config-
+ * driven (`reviewWorkflow.enabled` flag). The plan's wording around a
+ * config flag is one valid implementation; data-driven is honest:
+ * "if this item has review state, handle it; else no-op." When
+ * review-workflow ships its config field, no flag-check refactor is
+ * needed.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the archive ↔ review-state interaction.
+ *     `archive.ts`'s `handleArchive` calls one function (`prepareForArchive`)
+ *     and consumes its returned audit events; doesn't replicate state-
+ *     machine knowledge.
+ *   - DIP: `handleArchive` depends on the helper's typed return shape,
+ *     not on review-state field names baked into the route handler.
+ *   - OCP: when review-workflow ships its full state machine
+ *     (additional states, transitions like `pending-publish`), this
+ *     helper extends with new branches; archive route untouched.
+ */
+import type { ComponentManifest } from '../../types.js';
+import type { RecordEventInput } from '../../audit/context.js';
+/**
+ * Build the synthetic `review-withdraw` audit event emitted when
+ * archive auto-withdraws a `pending-review` submission. Per
+ * `design-soft-delete.md` Q9 audit shape lock.
+ *
+ * Returns `null` when the prior state isn't `pending-review` —
+ * other states (draft, approved) don't emit a synthetic withdraw.
+ * Approved state discards as part of the archive event itself
+ * (recorded via `priorReviewState` metadata).
+ */
+export declare function buildAutoWithdrawEvent(manifest: ComponentManifest, scope: {
+    kind: 'page' | 'fragment';
+    name: string;
+}): RecordEventInput | null;
+/**
+ * Compute additional metadata for the `archive` audit event capturing
+ * the item's prior review state. Returns an empty object for items
+ * without review state (current production behavior).
+ *
+ * `priorReviewState` is a non-prescriptive forensic record: the
+ * restore-always-to-draft invariant (Q9 N-B.1) means this metadata
+ * is never auto-applied on unarchive. It exists so operators can
+ * reconstruct "what state did this item have before it was archived?"
+ * via audit-log query alone, without re-reading the historical manifest.
+ */
+export declare function archiveReviewMetadata(manifest: ComponentManifest): Record<string, unknown>;
+/**
+ * Strip `reviewState` from a restored (unarchived) manifest. Per
+ * `design-soft-delete.md` Q9 N-B.1: restore always to draft; the
+ * absence of `reviewState` IS the draft state in the
+ * review-workflow's data model. Author re-submits if review needed.
+ *
+ * Returns the manifest unchanged when no review state was set.
+ */
+export declare function stripReviewStateForRestore(manifest: ComponentManifest): ComponentManifest;
+//# sourceMappingURL=archive-review.d.ts.map

package/dist/admin-api/routes/archive-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-review.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/archive-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAgB9D;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD,gBAAgB,GAAG,IAAI,CAczB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI1F;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,iBAAiB,CAIzF"}

package/dist/admin-api/routes/archive-review.js

@@ -0,0 +1,70 @@
+/**
+ * Read `reviewState` from a manifest without committing the field
+ * to `ComponentManifest`'s public type. The review-workflow
+ * foundation will lock the field's shape when it ships; until then,
+ * callers narrow at the read site.
+ *
+ * Returns the string state when present; `undefined` for live
+ * manifests today (every current production manifest).
+ */
+function readReviewState(manifest) {
+    const m = manifest;
+    return typeof m.reviewState === 'string' ? m.reviewState : undefined;
+}
+/**
+ * Build the synthetic `review-withdraw` audit event emitted when
+ * archive auto-withdraws a `pending-review` submission. Per
+ * `design-soft-delete.md` Q9 audit shape lock.
+ *
+ * Returns `null` when the prior state isn't `pending-review` —
+ * other states (draft, approved) don't emit a synthetic withdraw.
+ * Approved state discards as part of the archive event itself
+ * (recorded via `priorReviewState` metadata).
+ */
+export function buildAutoWithdrawEvent(manifest, scope) {
+    const priorState = readReviewState(manifest);
+    if (priorState !== 'pending-review')
+        return null;
+    return {
+        action: 'review-withdraw',
+        outcome: 'success',
+        scope,
+        metadata: {
+            autoWithdrawn: true,
+            reason: 'archive',
+            priorState,
+        },
+    };
+}
+/**
+ * Compute additional metadata for the `archive` audit event capturing
+ * the item's prior review state. Returns an empty object for items
+ * without review state (current production behavior).
+ *
+ * `priorReviewState` is a non-prescriptive forensic record: the
+ * restore-always-to-draft invariant (Q9 N-B.1) means this metadata
+ * is never auto-applied on unarchive. It exists so operators can
+ * reconstruct "what state did this item have before it was archived?"
+ * via audit-log query alone, without re-reading the historical manifest.
+ */
+export function archiveReviewMetadata(manifest) {
+    const priorState = readReviewState(manifest);
+    if (!priorState)
+        return {};
+    return { priorReviewState: priorState };
+}
+/**
+ * Strip `reviewState` from a restored (unarchived) manifest. Per
+ * `design-soft-delete.md` Q9 N-B.1: restore always to draft; the
+ * absence of `reviewState` IS the draft state in the
+ * review-workflow's data model. Author re-submits if review needed.
+ *
+ * Returns the manifest unchanged when no review state was set.
+ */
+export function stripReviewStateForRestore(manifest) {
+    if (readReviewState(manifest) === undefined)
+        return manifest;
+    const { reviewState: _strip, ...rest } = manifest;
+    return rest;
+}
+//# sourceMappingURL=archive-review.js.map

package/dist/admin-api/routes/archive-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-review.js","sourceRoot":"","sources":["../../../src/admin-api/routes/archive-review.ts"],"names":[],"mappings":"AA6CA;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,QAA2B;IAClD,MAAM,CAAC,GAAG,QAAyD,CAAA;IACnE,OAAO,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAA;AACtE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAA2B,EAC3B,KAAkD;IAElD,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC5C,IAAI,UAAU,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAA;IAEhD,OAAO;QACL,MAAM,EAAE,iBAAiB;QACzB,OAAO,EAAE,SAAS;QAClB,KAAK;QACL,QAAQ,EAAE;YACR,aAAa,EAAE,IAAI;YACnB,MAAM,EAAE,SAAS;YACjB,UAAU;SACX;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAA2B;IAC/D,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAA;IAC5C,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAA;IAC1B,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAA2B;IACpE,IAAI,eAAe,CAAC,QAAQ,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAA;IAC5D,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,QAAyD,CAAA;IAClG,OAAO,IAAyB,CAAA;AAClC,CAAC"}

package/dist/admin-api/routes/archive.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Archive / unarchive / purge routes for pages + fragments.
+ *
+ * Per `design-soft-delete.md`'s Cut 5 lock and the implementation
+ * grilling Q1 (one `archive.ts` module mounting both kinds): the
+ * lifecycle is the same shape for pages and fragments; the only
+ * axis that differs is the manifest filename + ItemRef source.
+ * Co-locating keeps "what does the archive lifecycle do?" answerable
+ * by reading one file.
+ *
+ * # The six routes
+ *
+ *   POST   /api/pages/:name/archive       (capability: delete:pages)
+ *   POST   /api/pages/:name/unarchive     (capability: edit:pages)
+ *   DELETE /api/pages/:name/purge         (capability: delete:pages)
+ *   POST   /api/fragments/:name/archive   (capability: delete:fragments)
+ *   POST   /api/fragments/:name/unarchive (capability: edit:fragments)
+ *   DELETE /api/fragments/:name/purge     (capability: delete:fragments)
+ *
+ * Capability assignment per implementation Q6 (locked F1): archive +
+ * purge are delete-class; unarchive is edit-class. Symmetric authority
+ * (delete-class to remove from production; edit-class to bring back).
+ *
+ * # Direct write, own pipeline (Q2 lock B1)
+ *
+ * Archive is a lifecycle event, not a content edit. Don't reuse the
+ * PUT pipeline — it would fire `beforeSave` / `afterSave` hooks built
+ * for content saves and run save-delta validation against the full
+ * schema. Archive flips a manifest field; the audit `action` is
+ * `archive` / `unarchive` / `purge`, NOT `save`.
+ *
+ * # Existing dep-sidecars untouched on archive (Q3 lock C1)
+ *
+ * Archived items keep their `asset-refs` and `fragment-deps` sidecars.
+ * An archive still references its assets / fragments — that's why an
+ * asset-purge attempt finds it. Tearing down on archive (and rebuilding
+ * on unarchive) would silently break refs whenever an asset got purged
+ * during the archive window. Tear-down happens on PURGE only.
+ *
+ * # `archive-aliases` reverse index (Cut 5a)
+ *
+ * Cut 5a shipped `archive-aliases.ts` — a per-edge sidecar at
+ * `.gazetta/alias-targets/{aliasTarget}/{encoded-source-item}`. The
+ * archive route writes it on archive-with-aliasOf; the purge route
+ * reads it (via `readArchivesAliasing`) for the alias-pointers part of
+ * the purge-blocked check. Per `team-preferences.md` rule 24: at the
+ * 5K-page envelope, walking every manifest to find aliases is ~30s on
+ * cloud; the sidecar is ~5ms `readDir`. Same pattern as `asset-refs`.
+ *
+ * # Purge-blocked: one 409 with both arrays (Q4 lock D1)
+ *
+ *   { code: 'DELETE_BLOCKED', aliases: [...], liveRefs: [...] }
+ *
+ * One 409, both arrays present. Surfaces every blocker in one
+ * round-trip; lets the author resolve in any order. UI gets one panel
+ * to render. Empty array when that class isn't blocking.
+ *
+ * # `?force=true` bypass (Q5 lock E1)
+ *
+ * Bypasses BOTH alias-pointers AND live-refs. One mental model — "I am
+ * an operator overriding the safety check." Audit records what was
+ * bypassed (`metadata.bypassedAliases` + `metadata.bypassedRefs`) so
+ * forensics finds what broke. Validators surface dangling aliases on
+ * the next save (P3); render emits 404 / errors on broken refs.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the archive lifecycle. Doesn't touch the
+ *     PUT pipeline (Q2 B1); doesn't touch dep-sidecars on archive
+ *     (Q3 C1). Each function answers one question.
+ *   - DIP: routes consume `SourceContextResolver` like every other
+ *     route module; archive primitives consume the typed `ItemKind`
+ *     parameter rather than branching on URL shape inside helpers.
+ */
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import type { SourceContextResolver } from '../source-context.js';
+import type { AuditEnv } from '../middleware/audit.js';
+import type { ItemRef } from '../../dep-sidecars.js';
+type ItemKind = 'page' | 'fragment';
+export interface ItemHandle {
+    /** ItemRef source axis (`page` | `fragment`); used for sidecar lookup. */
+    refSource: ItemRef['source'];
+    /** The audit + scope kind. Same value as `refSource`; named for clarity. */
+    scopeKind: ItemKind;
+    /** Manifest filename (`page.json` or `fragment.json`). */
+    filename: string;
+    /** Verbose name used in error messages. */
+    label: string;
+}
+export declare const PAGE_HANDLE: ItemHandle;
+export declare const FRAGMENT_HANDLE: ItemHandle;
+/**
+ * Background-scanner notification options for the archive lifecycle.
+ *
+ * Every archive transition (archive / unarchive / purge / setAlias)
+ * is a manifest write — it must notify the validation scanner so
+ * background-stage validators (P1: `referenced-archived-without-alias`,
+ * P2: `dangling-alias`, P5: `aliasof-points-to-archived`) re-run on
+ * the affected item and clear stale cache entries.
+ *
+ * Same shape as `manifest-save.ts`'s `scanner.rescan(cause)` call;
+ * fire-and-forget — the route response doesn't block on scanner work.
+ * Cross-foundation gap #6 from `testing-plan.md` punch list.
+ */
+export interface ArchiveRoutesOptions {
+    scanner?: import('../../validation/scanner.js').ValidationScanner | null;
+}
+export declare function archiveRoutes(resolve: SourceContextResolver, opts?: ArchiveRoutesOptions): Hono<AuditEnv, import("hono/types").BlankSchema, "/">;
+export declare function handleArchive(c: Context<AuditEnv>, resolve: SourceContextResolver, handle: ItemHandle, scanner?: import('../../validation/scanner.js').ValidationScanner | null): Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    code: "ARCHIVE_HAS_LIVE_REFS";
+    liveRefs: {
+        kind: "page" | "fragment";
+        name: string;
+    }[];
+}, 409, "json">) | (Response & import("hono").TypedResponse<{
+    ok: true;
+    name: string;
+    archivedAt: string;
+    aliasOf?: string | undefined;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function handlePurge(c: Context<AuditEnv>, resolve: SourceContextResolver, handle: ItemHandle, scanner?: import('../../validation/scanner.js').ValidationScanner | null): Promise<(Response & import("hono").TypedResponse<{
+    error: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    code: "DELETE_BLOCKED";
+    aliases: {
+        kind: "page" | "fragment";
+        name: string;
+    }[];
+    liveRefs: {
+        kind: "page" | "fragment";
+        name: string;
+    }[];
+}, 409, "json">) | (Response & import("hono").TypedResponse<{
+    ok: true;
+    name: string;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export {};
+//# sourceMappingURL=archive.d.ts.map

package/dist/admin-api/routes/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/admin-api/routes/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAIjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAmBpD,KAAK,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAEnC,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC5B,4EAA4E;IAC5E,SAAS,EAAE,QAAQ,CAAA;IACnB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;CACd;AAED,eAAO,MAAM,WAAW,EAAE,UAKzB,CAAA;AAED,eAAO,MAAM,eAAe,EAAE,UAK7B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,6BAA6B,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACzE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,qBAAqB,EAAE,IAAI,GAAE,oBAAyB,yDAoC5F;AAuBD,wBAAsB,aAAa,CACjC,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,EACpB,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,OAAO,6BAA6B,EAAE,iBAAiB,GAAG,IAAW;;;;;;;;;;;;;;;oEA+H/E;AAmJD,wBAAsB,WAAW,CAC/B,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,EACpB,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,OAAO,6BAA6B,EAAE,iBAAiB,GAAG,IAAW;;;;;;;;;;;;;;;;;oEA0F/E"}