@lovrozagar/oat 0.1.0

package/dist/runtime/async.js

@@ -0,0 +1,130 @@
+/**
+ * Async operation support.
+ *
+ * For an operation declared with `x-async`, the HTTP response is a receipt, not an outcome. oat
+ * drives the poll route to a terminal state and treats that payload as the real result — without
+ * this, an extraction or batch API is testable only as "returned 202", which for such an API is
+ * most of the surface.
+ */
+import { fillPath } from "./world.js";
+/**
+ * A single PostgREST-style predicate, reused here so `until`/`successWhen` speak the same
+ * language as the filter grammar rather than inventing a second one.
+ */
+export function matchesPredicate(record, expression) {
+    const segments = expression.split(".");
+    if (segments.length < 3)
+        return false;
+    const [field, op] = segments;
+    const raw = segments.slice(2).join(".");
+    const actual = record[field];
+    switch (op) {
+        case "eq":
+            return String(actual) === raw;
+        case "neq":
+            return String(actual) !== raw;
+        case "in":
+            return raw
+                .replace(/^\(|\)$/g, "")
+                .split(",")
+                .map((s) => s.trim())
+                .includes(String(actual));
+        case "is":
+            if (raw === "null")
+                return actual === null || actual === undefined;
+            if (raw === "true")
+                return actual === true;
+            if (raw === "false")
+                return actual === false;
+            return false;
+        default:
+            return false;
+    }
+}
+function readPath(body, path) {
+    let node = body;
+    for (const segment of path.replace(/^\$\.?/, "").split(".").filter(Boolean)) {
+        if (node === null || typeof node !== "object")
+            return undefined;
+        node = node[segment];
+    }
+    return node;
+}
+/**
+ * Polls until `until` matches, the timeout expires, or the poll route stops responding.
+ *
+ * Polling is capped by wall-clock rather than attempt count so a slow backend and a fast one
+ * behave the same way, and the interval is fixed rather than exponential — the point is to
+ * observe when the state changes, not to be gentle with an API oat is already hammering.
+ */
+export async function driveAsync(client, spec, receipt, scope, headers) {
+    const exchanges = [];
+    const began = performance.now();
+    const pollScope = { ...scope };
+    if (spec.idFrom !== undefined) {
+        const id = readPath(receipt, spec.idFrom);
+        if (id !== undefined && id !== null) {
+            /* The receipt names the job; bind it to whichever poll-path parameter is unresolved. */
+            const parameters = [...spec.poll.matchAll(/\{([^}]+)\}/g)].map((m) => m[1] ?? "");
+            const unbound = parameters.find((name) => pollScope[name] === undefined);
+            const target = unbound ?? spec.idFrom.replace(/^\$\./, "");
+            pollScope[target] = String(id);
+        }
+    }
+    const [method = "GET", template = spec.poll] = spec.poll.split(" ");
+    let path;
+    try {
+        path = fillPath(template, pollScope);
+    }
+    catch (error) {
+        return {
+            elapsedMs: performance.now() - began,
+            exchanges,
+            polls: 0,
+            succeeded: false,
+            terminal: null,
+            timedOut: false,
+        };
+    }
+    let polls = 0;
+    while (performance.now() - began < spec.timeoutMs) {
+        const exchange = await client.request(method, path, { headers });
+        exchanges.push(exchange);
+        polls += 1;
+        if (exchange.status < 300) {
+            const body = exchange.responseBody;
+            if (body !== null && typeof body === "object") {
+                const record = body;
+                const done = spec.until === undefined || matchesPredicate(record, spec.until);
+                if (done) {
+                    return {
+                        elapsedMs: performance.now() - began,
+                        exchanges,
+                        polls,
+                        succeeded: spec.successWhen === undefined || matchesPredicate(record, spec.successWhen),
+                        terminal: record,
+                        timedOut: false,
+                    };
+                }
+            }
+        }
+        else if (exchange.status === 404 && polls > 1) {
+            /* The job existed and then did not — a vanished job is terminal, and reporting it as a
+             * timeout would name the wrong problem. */
+            break;
+        }
+        await sleep(spec.pollIntervalMs);
+    }
+    return {
+        elapsedMs: performance.now() - began,
+        exchanges,
+        polls,
+        succeeded: false,
+        terminal: null,
+        timedOut: true,
+    };
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+//# sourceMappingURL=async.js.map

package/dist/runtime/async.js.map

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

package/dist/runtime/auth.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Credential acquisition and lifecycle.
+ *
+ * oat knows nothing about any login route. A principal declares a chain of steps; each step is
+ * an operation from the spec (or a raw request), values flow forward by JSON path, and anything
+ * delivered outside HTTP — verification tokens, OTPs, magic links — comes from a hook the caller
+ * writes. That hook is the entire backend-coupling surface.
+ */
+import type { AuthFlow, Hooks } from "../config/define-config.ts";
+import type { SpecModel } from "../spec/graph.ts";
+import type { Client } from "./client.ts";
+export type AcquireSpec = AuthFlow;
+export interface PrincipalRuntime {
+    id: string;
+    headers: () => Record<string, string>;
+    /** Address this principal was provisioned under, for cascade teardown. */
+    address: string | null;
+    /** Values bound during acquisition — roots discovered from the credential live here too. */
+    scope: Record<string, string>;
+    refreshIfStale: () => Promise<void>;
+    /** Forces reacquisition, used when a control probe proves the credential died early. */
+    reacquire: () => Promise<void>;
+    expiresAt: number | null;
+}
+export declare function readPath(body: unknown, path: string): unknown;
+/**
+ * Decodes a JWT expiry without verifying the signature — oat is reading its own credential to
+ * schedule a refresh, not making a trust decision about it.
+ */
+export declare function jwtClaims(credential: string): Record<string, unknown> | null;
+export declare function jwtExpiryMs(credential: string): number | null;
+export interface AcquireContext {
+    client: Client;
+    model: SpecModel;
+    hooks: Hooks;
+    principalId: string;
+}
+/** Runs the chain once, returning the credential and everything bound along the way. */
+export declare function runAcquireChain(spec: AcquireSpec, context: AcquireContext): Promise<{
+    credential: string;
+    scope: Record<string, string>;
+    expiresAt: number | null;
+}>;
+/** Wraps a chain in a credential that refreshes itself before it expires. */
+export declare function createPrincipal(id: string, spec: AcquireSpec, context: AcquireContext): Promise<PrincipalRuntime>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/runtime/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/runtime/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAY,KAAK,EAA8B,MAAM,4BAA4B,CAAA;AACvG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAY,MAAM,aAAa,CAAA;AAInD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAA;AAElC,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,wFAAwF;IACxF,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAU7D;AAkBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQ5E;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,KAAK,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACnB;AAED,wFAAwF;AACxF,wBAAsB,eAAe,CACpC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,cAAc,GACrB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA+E1F;AAgHD,6EAA6E;AAC7E,wBAAsB,eAAe,CACpC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,cAAc,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAmC3B"}

package/dist/runtime/auth.js

@@ -0,0 +1,236 @@
+/**
+ * Credential acquisition and lifecycle.
+ *
+ * oat knows nothing about any login route. A principal declares a chain of steps; each step is
+ * an operation from the spec (or a raw request), values flow forward by JSON path, and anything
+ * delivered outside HTTP — verification tokens, OTPs, magic links — comes from a hook the caller
+ * writes. That hook is the entire backend-coupling surface.
+ */
+export function readPath(body, path) {
+    let node = body;
+    for (const segment of path.replace(/^\$\.?/, "").split(".").filter(Boolean)) {
+        if (node === null || typeof node !== "object")
+            return undefined;
+        const index = Number.parseInt(segment, 10);
+        node = Array.isArray(node)
+            ? (Number.isNaN(index) ? undefined : node[index])
+            : node[segment];
+    }
+    return node;
+}
+/** `{name}` placeholders resolved from the accumulated scope. */
+function interpolate(value, scope) {
+    if (typeof value === "string") {
+        return value.replace(/\{([A-Za-z0-9_]+)\}/g, (match, key) => scope[key] ?? match);
+    }
+    if (Array.isArray(value))
+        return value.map((item) => interpolate(item, scope));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = interpolate(item, scope);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Decodes a JWT expiry without verifying the signature — oat is reading its own credential to
+ * schedule a refresh, not making a trust decision about it.
+ */
+export function jwtClaims(credential) {
+    const parts = credential.split(".");
+    if (parts.length !== 3 || parts[1] === undefined)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function jwtExpiryMs(credential) {
+    const claims = jwtClaims(credential);
+    return typeof claims?.exp === "number" ? claims.exp * 1000 : null;
+}
+/** Runs the chain once, returning the credential and everything bound along the way. */
+export async function runAcquireChain(spec, context) {
+    const scope = {};
+    let last;
+    for (const [index, step] of spec.steps.entries()) {
+        const stepBind = "bind" in step ? step.bind : undefined;
+        for (const [name, literal] of Object.entries(stepBind ?? {})) {
+            scope[name] = String(interpolate(literal, scope));
+        }
+        if ("outOfBand" in step) {
+            const address = String(interpolate(step.outOfBand.address, scope));
+            const value = await resolveOutOfBand(context, address, step.outOfBand.kind);
+            scope[step.outOfBand.as] = value;
+            continue;
+        }
+        const request = resolveRequest(step, context, scope, index);
+        last = await context.client.request(request.method, request.path, {
+            ...(request.body === undefined ? {} : { body: request.body }),
+            ...(request.headers === undefined ? {} : { headers: request.headers }),
+            ...(request.query === undefined ? {} : { query: request.query }),
+        });
+        const acceptable = ("expect" in step ? step.expect : undefined) ?? [];
+        const ok = acceptable.length > 0 ? acceptable.includes(last.status) : last.status < 300;
+        if (!ok) {
+            throw new Error(`oat: principal "${context.principalId}" failed at auth step ${index + 1} ` +
+                `(${request.method} ${request.path}): expected ` +
+                `${acceptable.length > 0 ? acceptable.join("/") : "2xx"}, got ${last.status} — ` +
+                `${JSON.stringify(last.responseBody).slice(0, 200)}`);
+        }
+        const saveClaimsFrom = "saveClaimsFrom" in step ? step.saveClaimsFrom : undefined;
+        if (saveClaimsFrom !== undefined) {
+            const token = readPath(last.responseBody, saveClaimsFrom.token);
+            const claims = typeof token === "string" ? jwtClaims(token) : null;
+            if (claims === null) {
+                throw new Error(`oat: auth step ${index + 1} for "${context.principalId}" expected a JWT at ` +
+                    `${saveClaimsFrom.token}, but it is absent or not decodable`);
+            }
+            for (const [name, claimPath] of Object.entries(saveClaimsFrom.bind)) {
+                const value = readPath(claims, claimPath);
+                if (value === undefined || value === null) {
+                    throw new Error(`oat: auth step ${index + 1} binds ${name} to claim "${claimPath}", which the token ` +
+                        `does not carry. Available claims: ${Object.keys(claims).join(", ")}`);
+                }
+                scope[name] = String(value);
+            }
+        }
+        const saveAs = "saveAs" in step ? step.saveAs : undefined;
+        for (const [name, path] of Object.entries(saveAs ?? {})) {
+            const value = readPath(last.responseBody, path);
+            if (value === undefined || value === null) {
+                throw new Error(`oat: auth step ${index + 1} for "${context.principalId}" declares saveAs.${name} = ` +
+                    `"${path}", which is not present in the response`);
+            }
+            scope[name] = String(value);
+        }
+    }
+    const credential = scope.credential ?? String(readPath(last?.responseBody, spec.credentialFrom) ?? "");
+    if (credential === "" || credential === "undefined") {
+        throw new Error(`oat: principal "${context.principalId}" completed its chain but ${spec.credentialFrom} ` +
+            "did not yield a credential");
+    }
+    return { credential, expiresAt: computeExpiry(spec, last, credential), scope };
+}
+function computeExpiry(spec, last, credential) {
+    /* Prefer what the API states, then what the credential itself carries, then the configured
+     * fallback. Guessing an expiry that is too long means requests start failing mid-run for
+     * reasons that look like backend defects. */
+    if (spec.expiresInFrom !== undefined) {
+        const seconds = readPath(last?.responseBody, spec.expiresInFrom);
+        if (typeof seconds === "number")
+            return Date.now() + seconds * 1000;
+    }
+    const fromJwt = jwtExpiryMs(credential);
+    if (fromJwt !== null)
+        return fromJwt;
+    if (spec.assumeTtlMs !== undefined)
+        return Date.now() + spec.assumeTtlMs;
+    return null;
+}
+function isOperationStep(step) {
+    return "operationId" in step;
+}
+function isRequestStep(step) {
+    return "method" in step && "path" in step;
+}
+function resolveRequest(step, context, scope, index) {
+    /* Two shapes, distinguished structurally: name an operation from the document, or give a raw
+     * method and path for an endpoint the document does not describe. */
+    if (isOperationStep(step)) {
+        const op = context.model.byOperationId.get(step.operationId);
+        if (op === undefined) {
+            throw new Error(`oat: auth step ${index + 1} names operation "${step.operationId}", which is not in the ` +
+                "document");
+        }
+        return {
+            method: op.method,
+            path: String(interpolate(op.path, scope)),
+            ...(step.body === undefined ? {} : { body: interpolate(step.body, scope) }),
+            ...(step.headers === undefined
+                ? {}
+                : { headers: interpolate(step.headers, scope) }),
+            ...(step.query === undefined
+                ? {}
+                : { query: interpolate(step.query, scope) }),
+        };
+    }
+    if (!isRequestStep(step)) {
+        throw new Error(`oat: auth step ${index + 1} declares neither an operationId nor a method and path`);
+    }
+    return {
+        method: step.method,
+        path: String(interpolate(step.path, scope)),
+        ...(step.body === undefined ? {} : { body: interpolate(step.body, scope) }),
+        ...(step.headers === undefined
+            ? {}
+            : { headers: interpolate(step.headers, scope) }),
+        ...(step.query === undefined
+            ? {}
+            : { query: interpolate(step.query, scope) }),
+    };
+}
+/**
+ * Out-of-band values usually land in an eventually-consistent store, so the hook is polled with
+ * backoff rather than called once. A single read that happens to race the write looks exactly
+ * like a broken delivery mechanism.
+ */
+async function resolveOutOfBand(context, address, kind) {
+    const hook = context.hooks.resolveOutOfBand;
+    if (hook === undefined) {
+        throw new Error(`oat: principal "${context.principalId}" needs a "${kind}" value delivered outside HTTP, ` +
+            "but the config declares no resolveOutOfBand hook. oat cannot read your mail catcher, " +
+            "KV store or webhook sink — supply a function that can.");
+    }
+    let delay = 200;
+    for (let attempt = 1; attempt <= 6; attempt++) {
+        const value = await hook({ address, attempt, kind });
+        if (value !== null && value !== "")
+            return value;
+        await new Promise((done) => setTimeout(done, delay));
+        delay = Math.min(delay * 2, 3000);
+    }
+    throw new Error(`oat: no "${kind}" value arrived for ${address} after 6 attempts. The delivery mechanism is ` +
+        "either slow beyond the backoff window or not firing at all.");
+}
+/** Wraps a chain in a credential that refreshes itself before it expires. */
+export async function createPrincipal(id, spec, context) {
+    let credential = "";
+    let expiresAt = null;
+    let scope = {};
+    const acquire = async () => {
+        const result = await runAcquireChain(spec, { ...context, principalId: id });
+        credential = result.credential;
+        expiresAt = result.expiresAt;
+        scope = result.scope;
+    };
+    await acquire();
+    const header = spec.header ?? "authorization";
+    const template = spec.template ?? "Bearer {credential}";
+    const runtime = {
+        /* Whatever the flow bound as an address is what teardown will cascade on. */
+        address: scope.address ?? scope.email ?? null,
+        expiresAt,
+        headers: () => ({ [header]: template.replace("{credential}", credential) }),
+        id,
+        reacquire: acquire,
+        /* Refresh at three quarters of the lifetime, before dispatch rather than mid-flight, so a
+         * run stays reproducible and no request is ever retried for timing reasons alone. */
+        refreshIfStale: async () => {
+            if (expiresAt === null)
+                return;
+            const issuedWindow = expiresAt - Date.now();
+            if (issuedWindow > 0 && issuedWindow < 0.25 * (spec.assumeTtlMs ?? 300_000))
+                await acquire();
+            else if (issuedWindow <= 0)
+                await acquire();
+        },
+        scope,
+    };
+    return runtime;
+}
+//# sourceMappingURL=auth.js.map

package/dist/runtime/auth.js.map

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

package/dist/runtime/checks.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The check registry.
+ *
+ * Each check asserts one property that must hold for any correct implementation. They need no
+ * ground truth — they compare the API against itself, through independent projections, or against
+ * the oracle of what oat just wrote. Check ids are stable: the conformance suite asserts on them.
+ */
+import type { InviteSpec } from "../spec/extensions.ts";
+import type { QueryCapability } from "../spec/extensions.ts";
+import type { OperationModel, SpecModel } from "../spec/graph.ts";
+import type { Client } from "./client.ts";
+import type { FindingCollector } from "./finding.ts";
+import type { SchemaValidator } from "./validate.ts";
+import { type Record_ } from "./world.ts";
+/** A resolved principal as checks see it — identity, lattice position, and how to speak as it. */
+export interface Actor {
+    id: string;
+    role: string | undefined;
+    /** Higher can do everything a lower rank can. Same rank = peers. */
+    rank: number;
+    headers: () => Record<string, string>;
+    /** Tenant identity from config / the auth flow — not the full path scope. */
+    roots: Record<string, string>;
+    scope: Record<string, string>;
+    /** Value the owner puts in an invite body for this principal. */
+    inviteAs: string | undefined;
+}
+export interface CheckContext {
+    entityName: string;
+    identity: string;
+    model: SpecModel;
+    client: Client;
+    findings: FindingCollector;
+    scope: Record<string, string>;
+    listOp: OperationModel;
+    readOp: OperationModel | undefined;
+    createOp: OperationModel | undefined;
+    updateOp: OperationModel | undefined;
+    deleteOp: OperationModel | undefined;
+    collectionKey: string | null;
+    records: Record_[];
+    query: QueryCapability | null;
+    softDelete: string | null;
+    invite: InviteSpec | null;
+    auth: () => Record<string, string>;
+    /**
+     * Every configured principal, primary first. Isolation checks still use `altAuth` (the first
+     * actor whose scope is a different tenant). Lattice checks walk this list by `rank`.
+     */
+    actors: Actor[];
+    /** Principal in a different tenant, when one is configured. Derived, not `principals[1]`. */
+    altAuth: (() => Record<string, string>) | undefined;
+    altScope: Record<string, string> | undefined;
+    validator: SchemaValidator | undefined;
+    seed: number;
+    /** Operations on this entity declared async via `x-async`. */
+    asyncOps: OperationModel[];
+    /** Operations on this entity that declare `x-effects`. */
+    effectOps: OperationModel[];
+}
+export interface Check {
+    id: string;
+    /** Skipped silently when the entity lacks the operations this check needs. */
+    applicable: (ctx: CheckContext) => boolean;
+    /**
+     * Check ids whose failure makes this one's result meaningless. When any has already fired for
+     * this entity, the check is skipped rather than reporting a consequence as a separate defect —
+     * one root cause should produce one finding, not a page of them.
+     */
+    dependsOn?: string[];
+    /**
+     * What this check needs in order to run at all, in the reader's terms.
+     *
+     * Reported when `applicable` returns false. Skipping silently would leave someone on an API
+     * shaped differently from the fixture believing a quiet run meant a clean one, when in truth
+     * half the suite never fired.
+     */
+    needs?: string;
+    /**
+     * Whether the check changes server state. Mutating checks run alone and in order; read-only
+     * checks batch together. Two writers racing on the same cohort would make each other's
+     * observations wrong, and the resulting finding would describe the interference rather than
+     * the backend.
+     */
+    mutates?: boolean;
+    run: (ctx: CheckContext) => Promise<void>;
+}
+export declare const CHECKS: readonly Check[];
+//# sourceMappingURL=checks.d.ts.map

package/dist/runtime/checks.d.ts.map

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