@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/credentials/effective.js

@@ -0,0 +1,25 @@
+/*
+ * The recipe one principal uses for one scheme. An override that names a kind replaces the base's
+ * kind, keeping only the options that belong to the scheme (`format`, `placements`): `refresh`,
+ * `expiresIn` and `holds` describe the replaced kind's credential. An override that names no kind
+ * merges its options over the base.
+ * Validation and the credential resolver both read recipes through this, so they cannot disagree.
+ */
+const KINDS = /* @__PURE__ */ new Set(["login", "mint", "static", "hook", "oauth2"]);
+const SCHEME_OPTIONS = /* @__PURE__ */ new Set(["format", "placements"]);
+export function effectiveRecipe(base, override) {
+    if (override === undefined)
+        return base;
+    if (base === undefined)
+        return override;
+    const namesKind = Object.keys(override).some((key) => KINDS.has(key) && override[key] !== undefined);
+    if (!namesKind)
+        return { ...base, ...override };
+    const options = Object.fromEntries(Object.entries(base).filter(([key]) => SCHEME_OPTIONS.has(key)));
+    return { ...options, ...override };
+}
+/** A config map's own entry: a principal or scheme named `constructor` is not the prototype's. */
+export function own(map, key) {
+    return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+//# sourceMappingURL=effective.js.map

package/dist/api/credentials/expiry.d.ts

@@ -0,0 +1,18 @@
+import type { ExpiresIn } from "../config/types/security.ts";
+/** What a credential's lifetime is computed from. */
+export interface ExpiryInput {
+    /** The recipe's lifetime: seconds, or where the issuing answer states them. */
+    expiresIn?: ExpiresIn | undefined;
+    /** The body of the answer that issued the value, a form answer's as its fields by name. */
+    body: unknown;
+    value: string;
+    /** Epoch ms when the value was issued. */
+    now: number;
+}
+/**
+ * When a credential lapses, in epoch ms: the lifetime the recipe or the issuing answer states, then
+ * the JWT's `exp`, then null for a value that never lapses as far as the API tester can tell. Guessing a lifetime
+ * too long makes requests fail mid-run for reasons that look like backend defects, so the API tester never guesses.
+ */
+export declare function expiresAtOf(input: ExpiryInput): number | null;
+//# sourceMappingURL=expiry.d.ts.map

package/dist/api/credentials/expiry.js

@@ -0,0 +1,24 @@
+import { jwtClaims } from "./jwt.js";
+import { readPath } from "../client/read-path.js";
+/**
+ * When a credential lapses, in epoch ms: the lifetime the recipe or the issuing answer states, then
+ * the JWT's `exp`, then null for a value that never lapses as far as the API tester can tell. Guessing a lifetime
+ * too long makes requests fail mid-run for reasons that look like backend defects, so the API tester never guesses.
+ */
+export function expiresAtOf(input) {
+    const seconds = secondsOf(input);
+    if (seconds !== undefined)
+        return input.now + seconds * 1000;
+    const exp = jwtClaims(input.value)?.["exp"];
+    return typeof exp === "number" ? exp * 1000 : null;
+}
+function secondsOf({ expiresIn, body }) {
+    if (typeof expiresIn === "number")
+        return expiresIn;
+    if (expiresIn === undefined)
+        return undefined;
+    const stated = readPath(body, expiresIn.from);
+    const seconds = typeof stated === "string" && stated.trim() !== "" ? Number(stated) : stated;
+    return typeof seconds === "number" && Number.isFinite(seconds) ? seconds : undefined;
+}
+//# sourceMappingURL=expiry.js.map

package/dist/api/credentials/interpolate.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialPrincipal } from "../config/types/hooks.ts";
+/** A `{principal.<key>}` placeholder the principal has no text value for. */
+export declare class MissingIdentityError extends Error {
+    readonly principal: string;
+    readonly key: string;
+    name: string;
+    constructor(principal: string, key: string);
+}
+/** The value with every `{principal.<key>}` filled, deep through arrays and plain objects. */
+export declare function fillPrincipal<T>(principal: CredentialPrincipal, value: T): T;
+/**
+ * Each identity value a `{principal.<key>}` in `value` fills, once, deep through arrays and plain
+ * objects. The id `{principal.id}` falls back to is the principal's name, which every report prints,
+ * so it is not one; a key the principal lacks is `fillPrincipal`'s to refuse.
+ */
+export declare function principalValues(principal: CredentialPrincipal, value: unknown): string[];
+/** The identity keys `text`'s `{principal.<key>}` placeholders read, in order. */
+export declare function principalKeysIn(text: string): string[];
+/** The value with the credential wherever `{credential}` stands, deep through arrays and plain objects. */
+export declare function fillCredential(value: unknown, credential: string): unknown;
+//# sourceMappingURL=interpolate.d.ts.map

package/dist/api/credentials/interpolate.js

@@ -0,0 +1,79 @@
+import { PRINCIPAL_PLACEHOLDER } from "../config/types/placeholder.js";
+/*
+ * `{principal.<key>}` in a recipe's strings and step bodies is the principal's identity data, filled
+ * before anything runs. `{principal.id}` falls back to the principal's id. Other `{name}` placeholders
+ * are the step runner's flow scope, and stay as they are.
+ */
+/** A `{principal.<key>}` placeholder the principal has no text value for. */
+export class MissingIdentityError extends Error {
+    principal;
+    key;
+    name = "MissingIdentityError";
+    constructor(principal, key) {
+        super(`principal "${principal}" has no text value for {principal.${key}}`);
+        this.principal = principal;
+        this.key = key;
+    }
+}
+/** The value with every `{principal.<key>}` filled, deep through arrays and plain objects. */
+export function fillPrincipal(principal, value) {
+    return fill(principal, value);
+}
+function fill(principal, value) {
+    if (typeof value === "string")
+        return value.replace(PRINCIPAL_PLACEHOLDER, (_, key) => textOf(principal, key));
+    if (Array.isArray(value))
+        return value.map((item) => fill(principal, item));
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fill(principal, item)]));
+}
+/**
+ * Each identity value a `{principal.<key>}` in `value` fills, once, deep through arrays and plain
+ * objects. The id `{principal.id}` falls back to is the principal's name, which every report prints,
+ * so it is not one; a key the principal lacks is `fillPrincipal`'s to refuse.
+ */
+export function principalValues(principal, value) {
+    const found = new Set();
+    const walk = (item) => {
+        if (typeof item === "string") {
+            for (const key of principalKeysIn(item)) {
+                const text = scalarText(principal.identity[key]);
+                if (text !== undefined)
+                    found.add(text);
+            }
+        }
+        else if (Array.isArray(item))
+            item.forEach(walk);
+        else if (item !== null && typeof item === "object")
+            Object.values(item).forEach(walk);
+    };
+    walk(value);
+    return [...found];
+}
+/** The identity keys `text`'s `{principal.<key>}` placeholders read, in order. */
+export function principalKeysIn(text) {
+    return [...text.matchAll(PRINCIPAL_PLACEHOLDER)].map(([, key]) => key);
+}
+/** The value with the credential wherever `{credential}` stands, deep through arrays and plain objects. */
+export function fillCredential(value, credential) {
+    if (typeof value === "string")
+        return value.replaceAll("{credential}", credential);
+    if (Array.isArray(value))
+        return value.map((item) => fillCredential(item, credential));
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fillCredential(item, credential)]));
+}
+function textOf(principal, key) {
+    const text = scalarText(principal.identity[key] ?? (key === "id" ? principal.id : undefined));
+    if (text === undefined)
+        throw new MissingIdentityError(principal.id, key);
+    return text;
+}
+function scalarText(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+        ? String(value)
+        : undefined;
+}
+//# sourceMappingURL=interpolate.js.map

package/dist/api/credentials/jwt.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A JWT's claims, decoded without verifying the signature: the API tester reads its own credential to know
+ * when it lapses and whose tenant it is, and makes no trust decision with it. Null when the value
+ * is not a JWT, or its payload is not a JSON object.
+ */
+export declare function jwtClaims(value: string): Record<string, unknown> | null;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/api/credentials/jwt.js

@@ -0,0 +1,20 @@
+/**
+ * A JWT's claims, decoded without verifying the signature: the API tester reads its own credential to know
+ * when it lapses and whose tenant it is, and makes no trust decision with it. Null when the value
+ * is not a JWT, or its payload is not a JSON object.
+ */
+export function jwtClaims(value) {
+    const parts = value.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        return claims !== null && typeof claims === "object" && !Array.isArray(claims)
+            ? claims
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=jwt.js.map

package/dist/api/credentials/origin-recipes.d.ts

@@ -0,0 +1,13 @@
+import type { SecurityScheme } from "../spec/security/schemes.ts";
+/** An origin as recipes read it: its `origins[].security` mapping, raw, and its document's schemes. */
+export interface OriginSchemes {
+    mapping: unknown;
+    schemes: ReadonlyMap<string, SecurityScheme>;
+}
+/** Each origin scheme a mapping names, to the recipe name it maps to. */
+export declare function mappedPairs(origin: OriginSchemes): Array<[scheme: string, recipe: string]>;
+/** The scheme each recipe name is for: the primary's own, then each origin-only recipe's origin scheme. */
+export declare function recipeSchemes(primary: ReadonlyMap<string, SecurityScheme>, origins: Iterable<OriginSchemes>): ReadonlyMap<string, SecurityScheme>;
+/** The recipe names only an origin's scheme is for: their format and placements are that scheme's own. */
+export declare function originOnlyRecipes(primary: ReadonlyMap<string, SecurityScheme>, origins: Iterable<OriginSchemes>): ReadonlySet<string>;
+//# sourceMappingURL=origin-recipes.d.ts.map

package/dist/api/credentials/origin-recipes.js

@@ -0,0 +1,23 @@
+/** Each origin scheme a mapping names, to the recipe name it maps to. */
+export function mappedPairs(origin) {
+    const { mapping, schemes } = origin;
+    if (typeof mapping !== "object" || mapping === null)
+        return [];
+    return Object.entries(mapping).filter((pair) => typeof pair[1] === "string" && schemes.has(pair[0]));
+}
+/** The scheme each recipe name is for: the primary's own, then each origin-only recipe's origin scheme. */
+export function recipeSchemes(primary, origins) {
+    const schemes = new Map(primary);
+    for (const origin of origins) {
+        for (const [scheme, recipe] of mappedPairs(origin)) {
+            if (!schemes.has(recipe))
+                schemes.set(recipe, origin.schemes.get(scheme));
+        }
+    }
+    return schemes;
+}
+/** The recipe names only an origin's scheme is for: their format and placements are that scheme's own. */
+export function originOnlyRecipes(primary, origins) {
+    return new Set([...recipeSchemes(primary, origins).keys()].filter((name) => !primary.has(name)));
+}
+//# sourceMappingURL=origin-recipes.js.map

package/dist/api/credentials/placeholders.d.ts

@@ -0,0 +1,10 @@
+/** A `{name}` a step reads that nothing before it fills: the step, counted from 1, and the name. */
+export interface Unfilled {
+    step: number;
+    name: string;
+}
+/** The first placeholder in `steps` that neither `given` nor an earlier binding fills. */
+export declare function unfilledIn(steps: readonly unknown[], given: Iterable<string>): Unfilled | undefined;
+/** Every name a chain of steps binds: what a refresh after it may read. */
+export declare function capturedBy(steps: readonly unknown[]): Set<string>;
+//# sourceMappingURL=placeholders.d.ts.map

package/dist/api/credentials/placeholders.js

@@ -0,0 +1,71 @@
+/*
+ * The `{name}` placeholders a chain of login or refresh steps reads, and the names it binds. The
+ * step runner fills each from the chain's scope: what the chain started from, then what each
+ * step's `bind`, `saveAs`, `saveClaimsFrom` and out-of-band `as` bound before it. A name nothing
+ * fills would be sent as written, so a recipe that reads one is refused, by name: at load, and
+ * before a request leaves. `{principal.<key>}` is the principal's identity, filled apart.
+ */
+import { placeholderNames } from "../config/types/placeholder.js";
+import { isRaw, isRawUnion, isRecord } from "../config/types/raw.js";
+/* A map the user keys, such as `bind` or `saveAs`; empty when it is not one. */
+const recordOf = (value) => (isRecord(value) ? value : {});
+const stepOf = (value) => (isRawUnion(value) ? value : {});
+const outOfBandOf = (step) => isRaw(step.outOfBand) ? step.outOfBand : {};
+const claimsOf = (step) => isRaw(step.saveClaimsFrom) ? step.saveClaimsFrom : {};
+/* What a step's request reads: a raw step's path, and its body, headers and query. An operation's path is the document's. */
+function requestReads(step) {
+    if (step.outOfBand !== undefined)
+        return placeholderNames(outOfBandOf(step).address);
+    return placeholderNames([step.method === undefined ? null : step.path, step.body, step.headers, step.query]);
+}
+/* Each `[name, template]` binding of a map, in order: a template may read the names bound before it. */
+function bindingsOf(value) {
+    return Object.entries(recordOf(value));
+}
+/** The first placeholder in `steps` that neither `given` nor an earlier binding fills. */
+export function unfilledIn(steps, given) {
+    const bound = new Set(given);
+    const missing = (value) => placeholderNames(value).find((name) => !bound.has(name));
+    for (const [index, value] of steps.entries()) {
+        const step = stepOf(value);
+        const name = unfilledStep(step, { bound, missing });
+        if (name !== undefined)
+            return { name, step: index + 1 };
+    }
+    return undefined;
+}
+/* One step in the engine's order: its binds, its request, its saveAs addresses, then its claims and out-of-band value. */
+function unfilledStep(step, at) {
+    const { bound, missing } = at;
+    for (const [name, template] of bindingsOf(step.bind)) {
+        const read = missing(template);
+        if (read !== undefined)
+            return read;
+        bound.add(name);
+    }
+    const read = requestReads(step).find((name) => !bound.has(name));
+    if (read !== undefined)
+        return read;
+    for (const [name, address] of bindingsOf(step.saveAs)) {
+        const unread = missing(address);
+        if (unread !== undefined)
+            return unread;
+        bound.add(name);
+    }
+    for (const name of boundAfter(step))
+        bound.add(name);
+    return undefined;
+}
+/* What a step binds once it is answered, beside `saveAs`: its claims, or the out-of-band value. */
+function boundAfter(step) {
+    const out = outOfBandOf(step);
+    return [...Object.keys(recordOf(claimsOf(step).bind)), ...(typeof out.as === "string" ? [out.as] : [])];
+}
+/** Every name a chain of steps binds: what a refresh after it may read. */
+export function capturedBy(steps) {
+    return new Set(steps.flatMap((value) => {
+        const step = stepOf(value);
+        return [...Object.keys(recordOf(step.bind)), ...Object.keys(recordOf(step.saveAs)), ...boundAfter(step)];
+    }));
+}
+//# sourceMappingURL=placeholders.js.map

package/dist/api/credentials/placement.d.ts

@@ -0,0 +1,23 @@
+import type { Recipe } from "../config/types/security.ts";
+import type { SecurityScheme } from "../spec/security/schemes.ts";
+import type { Sends } from "./ports.ts";
+/** The names and values a redactor must scrub, so no report, journal or repro shows them. */
+export interface Secrets {
+    headers: string[];
+    query: string[];
+    cookies: string[];
+    values: string[];
+}
+/** A scheme the document declares that the API tester has no way to send. */
+export declare class UnsupportedSchemeError extends Error {
+    readonly scheme: string;
+    readonly reason: string;
+    name: string;
+    constructor(scheme: string, reason: string);
+}
+/** The sends and the secrets for one value of one scheme, under the recipe's placement options. */
+export declare function sendsFor(scheme: SecurityScheme, recipe: Pick<Partial<Recipe>, "format" | "placements">, value: string): {
+    sends: Sends;
+    secrets: Secrets;
+};
+//# sourceMappingURL=placement.d.ts.map

package/dist/api/credentials/placement.js

@@ -0,0 +1,41 @@
+import { placementOf } from "../spec/security/placement.js";
+/** A scheme the document declares that the API tester has no way to send. */
+export class UnsupportedSchemeError extends Error {
+    scheme;
+    reason;
+    name = "UnsupportedSchemeError";
+    constructor(scheme, reason) {
+        super(`the API tester cannot send the "${scheme}" scheme: ${reason}`);
+        this.scheme = scheme;
+        this.reason = reason;
+    }
+}
+const PLACE_KEY = { cookie: "cookies", header: "headers", query: "query" };
+/** The sends and the secrets for one value of one scheme, under the recipe's placement options. */
+export function sendsFor(scheme, recipe, value) {
+    const placement = placementOf(scheme);
+    /* placementOf is null for exactly the unsupported kind. */
+    if (placement === null) {
+        throw new UnsupportedSchemeError(scheme.name, scheme.unsupported);
+    }
+    const credential = placement.encode === "base64" ? Buffer.from(value).toString("base64") : value;
+    const places = [
+        { ...placement, template: recipe.format ?? placement.template },
+        ...(recipe.placements ?? []).map((extra) => ({ ...extra, template: extra.template ?? "{credential}" })),
+    ];
+    const sends = { cookies: {}, headers: {}, query: {} };
+    const secrets = { cookies: [], headers: [], query: [], values: secretValues(placement, value, credential) };
+    for (const place of places) {
+        const key = PLACE_KEY[place.in];
+        sends[key][place.name] = place.template.replaceAll("{credential}", credential);
+        secrets[key].push(place.name);
+    }
+    return { secrets, sends };
+}
+/* The value, its encoding, and for a basic pair the bare password after the first colon; never empty text. */
+function secretValues(placement, value, credential) {
+    const colon = value.indexOf(":");
+    const password = placement.encode === "base64" && colon !== -1 ? [value.slice(colon + 1)] : [];
+    return [...new Set([value, credential, ...password])].filter((secret) => secret !== "");
+}
+//# sourceMappingURL=placement.js.map

package/dist/api/credentials/ports.d.ts

@@ -0,0 +1,96 @@
+import type { Hooks } from "../config/types/hooks.ts";
+import type { AuthStep } from "../config/types/steps.ts";
+export type { Sends } from "../config/types/hooks.ts";
+/** What an answer gives a recipe to read a credential, a lifetime or a claim from. */
+export interface StepAnswer {
+    status: number;
+    body: unknown;
+    headers: Readonly<Record<string, string>>;
+    cookies: Readonly<Record<string, string>>;
+}
+/** How a credential hop is sent: `probe` when it is meant to be refused, so its exchange is labeled one. */
+export interface Hop {
+    probe?: true;
+}
+/**
+ * Runs login and refresh steps, each once: `bind`, `saveAs`, `saveClaimsFrom` and `outOfBand` as in a
+ * scenario. It resolves with the scope the steps bound and the last answer, and rejects with an Error
+ * whose message is the reason when a step fails or a value is missing.
+ */
+export interface StepRunner {
+    run(steps: readonly AuthStep[], input: {
+        principal: string;
+        scope: Readonly<Record<string, string>>;
+        /** Where each answer holds a credential: registered as secrets before the answer is recorded. */
+        secrets?: readonly string[];
+    } & Hop): Promise<{
+        scope: Record<string, string>;
+        answer: StepAnswer;
+    }>;
+}
+/**
+ * Calls a documented operation as a principal sending one scheme, for mint and revoke: the run's
+ * client places that scheme's credential, refreshing it on a 401 like any request. `scope` fills
+ * the operation's path parameters, over the principal's own. It resolves with whatever the backend
+ * answered, and rejects with the reason when the principal holds no credential for the scheme.
+ */
+export interface OperationCaller {
+    call(input: {
+        operationId: string;
+        body?: unknown;
+        as: {
+            principal: string;
+            scheme: string;
+        };
+        scope?: Readonly<Record<string, string>>;
+        /**
+         * Send this value as the scheme's credential, placed and redacted like it, instead of what the
+         * principal holds: the one session a revoke ends. Never renewed on a 401.
+         */
+        value?: string;
+        /** Where the answer holds a credential, as `from` addresses it: a secret before the answer is recorded. */
+        secrets?: readonly string[];
+    }): Promise<StepAnswer>;
+}
+/**
+ * The record a minted credential is, named as its declared revoke would remove it: the revoke
+ * operation, the scope that fills its path, and who sends it.
+ */
+export interface CredentialRecord {
+    operationId: string;
+    scope: Readonly<Record<string, string>>;
+    as: {
+        principal: string;
+        scheme: string;
+    };
+}
+/** What the run knows of a minted credential's record, so teardown never revokes a key twice. */
+export interface CredentialRecords {
+    /** Whether the run already saw an accepted DELETE remove the record. */
+    removed(record: CredentialRecord): boolean;
+    /** Whether the document's read of the record shows it gone; false when nothing can read it. */
+    gone(record: CredentialRecord): Promise<boolean>;
+}
+/** POSTs a form, `application/x-www-form-urlencoded`, to an OAuth 2 token URL. */
+export interface TokenPoster {
+    post(url: string, form: Readonly<Record<string, string>>, hop?: Hop): Promise<StepAnswer>;
+}
+/**
+ * The run's redactor, as a recipe registers a value it sends from a principal's identity: never
+ * printed from then on, whatever its key is called. Too-short values are ignored, as for any secret.
+ */
+export interface SecretRegistry {
+    register(value: string): void;
+}
+/** `hooks.resolveCredential`, as a `{ hook: true }` recipe calls it. */
+export type CredentialHook = NonNullable<Hooks["resolveCredential"]>;
+/** Every port a run lends the credentials library. The hook is absent when the config sets none. */
+export interface CredentialPorts {
+    steps: StepRunner;
+    operations: OperationCaller;
+    records: CredentialRecords;
+    tokens: TokenPoster;
+    secrets: SecretRegistry;
+    resolveCredential?: CredentialHook;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/api/credentials/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/api/credentials/probe-principal.d.ts

@@ -0,0 +1,9 @@
+/** The `n`th probe principal of `owner`. */
+export declare function probePrincipal(owner: string, n: number): string;
+/** The principal a probe principal was made for; any other principal is its own. */
+export declare function probeOwner(principal: string): string;
+/** `text` with every probe principal named by its owner: what a reason a report carries must say. */
+export declare function withoutProbes(text: string): string;
+/** Whether `principal` is a dedicated credential's probe principal. */
+export declare function isProbePrincipal(principal: string): boolean;
+//# sourceMappingURL=probe-principal.d.ts.map

package/dist/api/credentials/probe-principal.js

@@ -0,0 +1,23 @@
+/*
+ * The principal a dedicated credential is held under: `<owner>#probe-<n>`. The store enrolls it so
+ * the credential is never the owner's own session; nothing else ever sees it. An exchange, a finding
+ * or a teardown record names the owner instead, so no file a run writes carries a probe's id.
+ */
+const SUFFIX = /#probe-\d+$/;
+/** The `n`th probe principal of `owner`. */
+export function probePrincipal(owner, n) {
+    return `${owner}#probe-${n}`;
+}
+/** The principal a probe principal was made for; any other principal is its own. */
+export function probeOwner(principal) {
+    return principal.replace(SUFFIX, "");
+}
+/** `text` with every probe principal named by its owner: what a reason a report carries must say. */
+export function withoutProbes(text) {
+    return text.replaceAll(/#probe-\d+/g, "");
+}
+/** Whether `principal` is a dedicated credential's probe principal. */
+export function isProbePrincipal(principal) {
+    return SUFFIX.test(principal);
+}
+//# sourceMappingURL=probe-principal.js.map

package/dist/api/credentials/read.d.ts

@@ -0,0 +1,4 @@
+import type { StepAnswer } from "./ports.ts";
+/** The text at an address of an answer: a non-empty string, or a number as text; else undefined. */
+export declare function readAnswer(answer: StepAnswer, address: string): string | undefined;
+//# sourceMappingURL=read.d.ts.map

package/dist/api/credentials/read.js

@@ -0,0 +1,16 @@
+import { readPath } from "../client/read-path.js";
+import { answerBody, readSaveAs } from "../runtime/cookies/save-as.js";
+/*
+ * Reading a credential, a lifetime or a claim out of an answer. A recipe's `from` takes the same
+ * address forms as `saveAs`: a JSON path of the body (dotted, a JSON pointer, or a filter, read
+ * as everywhere else in the API tester), `header:<name>` or `cookie:<name>`. A form answer, by its media type,
+ * is read by the same addresses, its top-level fields only.
+ */
+/** The text at an address of an answer: a non-empty string, or a number as text; else undefined. */
+export function readAnswer(answer, address) {
+    const value = readSaveAs(address, { ...answer, body: answerBody(answer), readJson: readPath });
+    if (typeof value === "number")
+        return String(value);
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+//# sourceMappingURL=read.js.map

package/dist/api/credentials/recipes/acquire.d.ts

@@ -0,0 +1,7 @@
+import type { Recipe, RecipeKind } from "../../config/types/security.ts";
+import type { AcquireCtx, Issued } from "./types.ts";
+/** The kind a recipe names, or undefined when it names none. Validation makes it exactly one. */
+export declare function recipeKind(recipe: Partial<Recipe>): RecipeKind | undefined;
+/** Acquires a credential by the kind the effective recipe names. */
+export declare function acquireRecipe(ctx: AcquireCtx, recipe: Partial<Recipe>): Promise<Issued>;
+//# sourceMappingURL=acquire.d.ts.map

package/dist/api/credentials/recipes/acquire.js

@@ -0,0 +1,32 @@
+import { acquireHook } from "./hook.js";
+import { acquireLogin } from "./login.js";
+import { acquireMint } from "./mint.js";
+import { acquireOAuth2 } from "./oauth2.js";
+import { acquireStatic } from "./static.js";
+/** The kind a recipe names, or undefined when it names none. Validation makes it exactly one. */
+export function recipeKind(recipe) {
+    if (recipe.login !== undefined)
+        return "login";
+    if (recipe.mint !== undefined)
+        return "mint";
+    if (recipe.static !== undefined)
+        return "static";
+    if (recipe.hook !== undefined)
+        return "hook";
+    return recipe.oauth2 === undefined ? undefined : "oauth2";
+}
+/** Acquires a credential by the kind the effective recipe names. */
+export function acquireRecipe(ctx, recipe) {
+    if (recipe.login !== undefined)
+        return acquireLogin(ctx, recipe.login, recipe);
+    if (recipe.mint !== undefined)
+        return acquireMint(ctx, recipe.mint, recipe);
+    if (recipe.static !== undefined)
+        return acquireStatic(ctx, recipe.static, recipe);
+    if (recipe.hook !== undefined)
+        return acquireHook(ctx, recipe);
+    if (recipe.oauth2 !== undefined)
+        return acquireOAuth2(ctx, recipe.oauth2, recipe);
+    return Promise.reject(new Error(`the ${ctx.scheme.name} recipe names no kind (login, mint, static, hook or oauth2)`));
+}
+//# sourceMappingURL=acquire.js.map

package/dist/api/credentials/recipes/answer.d.ts

@@ -0,0 +1,14 @@
+import type { StepAnswer } from "../ports.ts";
+import type { AcquireCtx } from "./types.ts";
+/** A call answered with a status other than 2xx, which it keeps. */
+export declare class RefusedAnswer extends Error {
+    readonly status: number;
+    constructor(what: string, status: number);
+}
+/** Refuses an answer that is not 2xx: `what` says which call it was. */
+export declare function answered(answer: StepAnswer, what: string): void;
+/** The credential at `from` in an answer, or a reason naming where it was looked for and the answer's type. */
+export declare function valueAt(answer: StepAnswer, from: string, what: string): string;
+/** Refuses scopes a static or hooked credential does not say it holds. */
+export declare function assertHolds(ctx: AcquireCtx, holds: readonly string[] | undefined): void;
+//# sourceMappingURL=answer.d.ts.map

package/dist/api/credentials/recipes/answer.js

@@ -0,0 +1,32 @@
+import { describeAnswerType } from "../../runtime/cookies/save-as.js";
+import { readAnswer } from "../read.js";
+/* What every recipe asks of an answer and of the scopes it is acquiring for. */
+/** A call answered with a status other than 2xx, which it keeps. */
+export class RefusedAnswer extends Error {
+    status;
+    constructor(what, status) {
+        super(`${what} answered ${status}`);
+        this.status = status;
+    }
+}
+/** Refuses an answer that is not 2xx: `what` says which call it was. */
+export function answered(answer, what) {
+    if (answer.status < 200 || answer.status >= 300)
+        throw new RefusedAnswer(what, answer.status);
+}
+/** The credential at `from` in an answer, or a reason naming where it was looked for and the answer's type. */
+export function valueAt(answer, from, what) {
+    const value = readAnswer(answer, from);
+    if (value === undefined)
+        throw new Error(`${what} answered no credential at ${from} (${describeAnswerType(answer.headers)})`);
+    return value;
+}
+/** Refuses scopes a static or hooked credential does not say it holds. */
+export function assertHolds(ctx, holds) {
+    const held = new Set(holds);
+    const missing = ctx.scopes.filter((scope) => !held.has(scope));
+    if (missing.length > 0) {
+        throw new Error(`the "${ctx.scheme.name}" credential does not hold ${missing.join(", ")}`);
+    }
+}
+//# sourceMappingURL=answer.js.map