@jini-ai/cms 0.5.2 → 0.5.3

package/dist/redirects/redirects.d.ts

@@ -0,0 +1,226 @@
+/**
+ * @file THE `redirects` write chokepoint (SPEC-009 REQ-01/04/05/06/07/08/13/
+ * 14/22/26; ADR-PIPE-009 C-001..C-004).
+ *
+ * Purpose:
+ * `createRedirect`/`updateRedirect`/`tombstoneRedirect`/`importRedirects` —
+ * the single manual-write entry point for redirect rules. Validates the
+ * pattern (via `RedirectMatcher.validatePattern`), rejects unsafe targets —
+ * absolute ones against the origin allowlist and site-relative ones against
+ * the admin application's own URL space (write-path open-redirect oracle,
+ * REQ-08; see `assertTargetAllowed`) — collapses/rejects
+ * one-hop chains (INV-04), enforces the exact-match dedup rule
+ * (behavior.spec.md §5.1), and writes the record + its revision in one
+ * transaction via `ports.internal.ts`'s shared `insertRedirectAndRevision`
+ * (INV-01/INV-07 — no other file writes `redirects`/`redirect_revisions`).
+ *
+ * Architectural role:
+ * Feature logic. No Express/route code — route handlers (Phase 2) call these
+ * functions directly and map thrown typed errors to HTTP codes per
+ * errors.spec.md.
+ */
+import { type Clock as ClockPort, type IdGenerator as IdGeneratorPort } from "@jini-ai/core/primitives";
+import { type OutboxPort } from "../core/index.js";
+import type { OriginRegistryPort } from "@jini-ai/http-kit/verified-origin";
+import { type RedirectDbHandle } from "./ports.internal.js";
+import type { RedirectMatcher, RedirectRepoPort } from "./ports.js";
+import type { CreateRedirectInput, RedirectMatchType, RedirectRecord, RedirectStatusCode, UpdateRedirectInput } from "./types.js";
+export declare const MIN_TARGET_LENGTH = 1;
+export declare const MAX_TARGET_LENGTH = 2048;
+export declare const MIN_PRIORITY = 0;
+export declare const MAX_PRIORITY = 1000;
+export declare const VALID_STATUS_CODES: readonly RedirectStatusCode[];
+export declare const MAX_IMPORT_BATCH_SIZE = 500;
+/**
+ * The removal primitive this domain is handed, rather than one it implements.
+ *
+ * Structurally typed ON PURPOSE — `features/redirects` imports nothing from `features/trash`, and
+ * must not. The composition root binds the real implementation (marker flip AND Trash index row, in
+ * one transaction) pre-bound to this domain's entity type. `display` is required so the two strings
+ * the Trash screen shows come from columns the caller already holds.
+ */
+export type RemoveRedirectFn = (required: {
+    workspaceId: string;
+    id: string;
+    display: {
+        title: string;
+        subtitle?: string | null;
+    };
+    at: string;
+    expectedVersion: number | null;
+    actor: {
+        principalId: string;
+        pluginId?: string | null;
+    };
+}) => Promise<{
+    ok: true;
+    version: number | null;
+} | {
+    ok: false;
+    reason: "not-found" | "version-changed";
+}>;
+export interface RedirectsWriteDeps {
+    repo: RedirectRepoPort;
+    /** See {@link RemoveRedirectFn}. Replaces `tombstoneRedirect`'s own `status` write. */
+    remove: RemoveRedirectFn;
+    /**
+     * Whether this rule has a Trash index row (S7, web-high fix plan 2026-09-24) — the thing
+     * `tombstoneRedirect` creates and Trash restore/purge match on, and NOT the same thing as
+     * `status === "disabled"` (an ordinary toggle-off has no Trash row at all). Structurally typed,
+     * same discipline as {@link RemoveRedirectFn}: this domain imports nothing from `features/trash`.
+     */
+    isInTrash: (required: {
+        workspaceId: string;
+        id: string;
+    }) => Promise<boolean>;
+    /**
+     * Un-trashes this rule (S7). Mirrors `TrashPort.restore`'s outcome union structurally, again
+     * without importing `features/trash`. `"adapter-unavailable"` is not reachable for redirects (the
+     * composition root always registers an adapter for `REDIRECT_ENTITY_TYPE`), but is part of the
+     * union it mirrors.
+     */
+    restore: (required: {
+        workspaceId: string;
+        id: string;
+        at: string;
+        actor: {
+            principalId: string;
+            pluginId?: string | null;
+        };
+    }) => Promise<"restored" | "not-found" | "version-changed" | "adapter-unavailable">;
+    /** The shared, non-tx-opening write handle (Decision A) — used via `ports.internal.ts`. */
+    db: RedirectDbHandle;
+    /** Opens/commits/rolls back the chokepoint's own transaction around a write. */
+    transaction: <T>(fn: () => Promise<T>) => Promise<T>;
+    matcher: RedirectMatcher;
+    originRegistry: OriginRegistryPort;
+    /** First path segments reserved by the composing host; no product-policy default. */
+    reservedSegments: ReadonlySet<string>;
+    clock: ClockPort;
+    idGen: IdGeneratorPort;
+    outbox: OutboxPort;
+}
+/**
+ * The site-relative half of the write gate: routing's structural + reserved-path verdict, then the
+ * redirect oracle's own raw-character rule. The read path hands a relative location to that oracle
+ * by concatenation, so a target it refuses (a raw backslash, any whitespace) would be stored and
+ * never fire; refusing it here keeps write and read agreeing. Checked SECOND so the more specific
+ * routing reasons (off-origin, control character, reserved) keep their own wording — a bare
+ * backslash target is `ok` to `checkSiteRelativeTarget` (on this site, `\` really does resolve to
+ * `/`), so only this second check ever refuses it (t91 B2, 2026-09-16). Last, the exact target
+ * `back`, which Express serves as the visitor's `Referer` instead of a path (see
+ * `./referrer-alias.ts`; t91 review F1, 2026-09-16).
+ *
+ * Exported as THE check for any caller-chosen, site-relative `Location` (t91 open-redirect fix,
+ * 2026-09-16): `routes/site/store.ts`'s `returnTo` had its own `startsWith("/") && !startsWith("//")`
+ * copy, which `/\evil.example` walks straight through. A caller that needs a path-absolute value
+ * still checks `startsWith("/")` itself — this function also accepts relative references (`new`,
+ * `?x`), which stay on-site but resolve against the current URL.
+ *
+ * @param required.target - The untrusted reference exactly as received, before any `new URL()` parse. Anything
+ * that is not site-relative (an absolute or protocol-relative URL, `javascript:`) is refused too.
+ * @returns The reason clause, or `null` when the target is allowed.
+ * @complexity O(n) in the target length.
+ * @example siteRelativeTargetReason({ target: "/products", reservedSegments }, {}); // => null
+ * @example siteRelativeTargetReason({ target: "/\\evil.example", reservedSegments }, {}) !== null; // => true
+ */
+export declare function siteRelativeTargetReason({ target, reservedSegments }: {
+    target: string;
+    reservedSegments: ReadonlySet<string>;
+}, _optional?: Record<string, never>): string | null;
+/**
+ * Pure precondition check mirroring every validator `createRedirect`/`updateRedirect` run, with NO
+ * write — `features/redirects/publish-content.ts`'s `precheck()` reuses this so the two can never
+ * drift onto different rulesets. Returns the refusal message a create/update against these exact
+ * fields would throw, or `null` when nothing would block.
+ *
+ * @param excludeId Mirrors {@link assertNoDuplicate}'s own parameter — the destination's own row id,
+ * when checking an update against itself.
+ * @complexity O(n) in `toTarget`'s length, plus the repo/origin reads each check makes — identical
+ * cost to `createRedirect`'s own validation pass, since this runs the exact same sequence.
+ */
+export declare function checkRedirectFieldsWouldWrite({ deps, fields }: {
+    deps: RedirectsWriteDeps;
+    fields: {
+        workspaceId: string;
+        matchType: RedirectMatchType;
+        fromPattern: string;
+        toTarget: string;
+        statusCode: RedirectStatusCode;
+        priority: number;
+    };
+}, { excludeId }?: {
+    excludeId?: string;
+}): Promise<string | null>;
+export interface CreateRedirectRequired {
+    deps: RedirectsWriteDeps;
+    input: CreateRedirectInput;
+    /**
+     * Provenance to stamp on the created record (REQ-01/26). Defaults to
+     * `'manual'`. `importRedirects` (C-004) passes `'import'` here — this is
+     * an internal parameter, not part of `CreateRedirectInput`'s public shape
+     * (an API caller never chooses their own provenance).
+     */
+    source?: "manual" | "import";
+}
+/** C-001: manual-create entry point (REQ-01). */
+export declare function createRedirect(required: CreateRedirectRequired, _optional?: Record<string, never>): Promise<{
+    record: RedirectRecord;
+}>;
+export interface UpdateRedirectRequired {
+    deps: RedirectsWriteDeps;
+    input: UpdateRedirectInput;
+}
+/**
+ * C-002: symmetric chokepoint entry for updates (REQ-04). A disable-only update
+ * ({@link isDisableOnlyUpdate}) writes the status change without re-validating the unchanged fields
+ * — it stores the existing target as-is, with no one-hop collapse.
+ *
+ * S7 (web-high fix plan 2026-09-24): a rule with a Trash index row (`deps.isInTrash`, distinct from
+ * `status === "disabled"` — see {@link RedirectsWriteDeps.isInTrash}'s own doc) refuses every update
+ * EXCEPT a pure `status: "active"` PATCH ({@link isRestoreOnlyUpdate}), which restores it instead of
+ * editing a row the caller cannot see the current shape of.
+ *
+ * @throws {EntityNotLiveError} On a non-restore update to a rule in the Trash.
+ * @throws {RedirectConflictError} If the Trash row's version moved before the restore landed.
+ */
+export declare function updateRedirect(required: UpdateRedirectRequired, _optional?: Record<string, never>): Promise<{
+    record: RedirectRecord;
+}>;
+export interface TombstoneRedirectRequired {
+    deps: RedirectsWriteDeps;
+    input: {
+        workspaceId: string;
+        id: string;
+        actorId: string;
+        pluginId?: string;
+    };
+}
+/** C-003: soft-delete (REQ-05). */
+export declare function tombstoneRedirect(required: TombstoneRedirectRequired, _optional?: Record<string, never>): Promise<{
+    record: RedirectRecord;
+}>;
+export interface ImportRedirectsRequired {
+    deps: RedirectsWriteDeps;
+    input: {
+        workspaceId: string;
+        actorId: string;
+        rules: CreateRedirectInput[];
+    };
+}
+export interface ImportRedirectsFailure {
+    index: number;
+    code: string;
+    message: string;
+}
+/**
+ * C-004: batch-create reusing the same chokepoint, no bypass (REQ-26). Each
+ * item is processed independently through `createRedirect` — NOT one shared
+ * transaction across items (EC-08); a per-item failure does not abort
+ * already-written prior items.
+ */
+export declare function importRedirects(required: ImportRedirectsRequired, _optional?: Record<string, never>): Promise<{
+    created: RedirectRecord[];
+    failed: ImportRedirectsFailure[];
+}>;
+//# sourceMappingURL=redirects.d.ts.map