@sekyro/node 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/connector-CMHuC-CU.d.ts

@@ -0,0 +1,384 @@
+import { W as WebhookEventType, L as Locale, C as CreatedSession, S as Sekyro, F as FetchLike } from './client-DUMp_I-1.js';
+
+/**
+ * The Sekyro claim contract and its only state machine, `mergeClaim` (spec
+ * 2026-10-29 §4). Pure: no I/O, no `jose`, no `node:` built-ins, so it runs in
+ * an edge runtime as well as on Node.
+ */
+/** The claim contract version this SDK writes and reads. @public */
+declare const CLAIM_VERSION = 1;
+/**
+ * Security facts a claim can carry: `face_mismatch` (a step-up failed because
+ * the face belongs to another subject), `duplicate` (the face matched another
+ * subject), `revoked` (the subject was revoked or deleted).
+ * @public
+ */
+type ClaimFlag = "face_mismatch" | "duplicate" | "revoked";
+/**
+ * The small object a connector stores on the auth provider's user and the
+ * session token carries (spec §4.1). Timestamps are unix seconds. It never
+ * carries a name, a document number, a photo, a score or the risk block.
+ * @public
+ */
+interface SekyroClaim {
+    /** Contract version; a reader refuses a higher one. */
+    v: 1;
+    /** The highest level the person proved for this app; `0` after a revocation. */
+    level: 0 | 1 | 2 | 3;
+    /** The assurance of the session that proved `level` (`none` when it had none). */
+    assurance: string;
+    /** Unix seconds: when `level` was proved. */
+    verified_at: number;
+    /** Unix seconds: the latest approved re-check; absent until one ran. */
+    rechecked_at?: number;
+    /** The session that set `level`. */
+    session_id: string;
+    /** The Sekyro subject, when known (needed to apply a revocation). */
+    subject_id?: string;
+    /** The environment the proof comes from. */
+    env: "live" | "sandbox";
+    /** Sorted and deduplicated; absent when empty. */
+    flags?: ClaimFlag[];
+}
+/**
+ * A terminal session result in the shape {@link mergeClaim} reads, built from
+ * a verified result token, a webhook or a session view.
+ * @public
+ */
+interface VerificationResultInput {
+    sessionId: string;
+    outcome: "approved" | "rejected" | "review" | null;
+    level: 0 | 1 | 2 | 3 | null;
+    assurance: string | null;
+    /** ISO 8601. */
+    verifiedAt: string;
+    env: "live" | "sandbox";
+    subjectId?: string;
+    reuseMode?: "recheck" | "step_up";
+    returning?: boolean;
+    subjectConflict?: boolean;
+    /** `true` when the session reported at least one duplicate subject. */
+    duplicates?: boolean;
+}
+/**
+ * What happened, as {@link mergeClaim} sees it. On a revocation or deletion,
+ * `userInExternalRefs` is `true` when the event's external references (or the
+ * subject's, read with the API key) include this user's id: a stored claim
+ * without `subject_id` is revoked only then, otherwise it is `subject_mismatch`.
+ * @public
+ */
+type MergeEvent = {
+    kind: "result";
+    result: VerificationResultInput;
+} | {
+    kind: "revoked";
+    subjectId: string;
+    userInExternalRefs?: boolean;
+} | {
+    kind: "deleted";
+    subjectId: string;
+    userInExternalRefs?: boolean;
+};
+/** The rule {@link mergeClaim} applied. @public */
+type MergeRule = "created" | "raised" | "renewed" | "rechecked" | "face_mismatch" | "revoked" | "revoked_ignored" | "not_approved" | "stale_ignored" | "env_mismatch" | "unsupported_version" | "subject_mismatch" | "no_change";
+/** Result of {@link mergeClaim}: write `claim` only when `changed`. @public */
+interface MergeOutcome {
+    claim: SekyroClaim | null;
+    changed: boolean;
+    rule: MergeRule;
+}
+/**
+ * Read a stored or token-carried claim: an object or its JSON string.
+ * Returns `null` when the value is not a claim. A claim with a higher
+ * version than {@link CLAIM_VERSION} is returned as-is (the caller refuses
+ * it); unknown keys and unknown flags of a current claim are dropped.
+ * @public
+ */
+declare function parseClaim(value: unknown): SekyroClaim | null;
+/**
+ * Apply one event to the stored claim (spec §4.2) and say whether to write.
+ * Pure and idempotent: the webhook and the return-URL path converge on one
+ * write, a retry is a no-op, an older result never overwrites a newer one, a
+ * failed attempt never erases a proof, a weaker proof never lowers the level,
+ * a result from another environment is refused, and a revoked claim stays
+ * revoked (`revoked_ignored`) until a session of another, known subject
+ * proves a level again.
+ *
+ * @param previous - The stored value (object, JSON string or nothing).
+ * @param event - A session result, or a revocation or deletion of a subject.
+ * @param opts - `env`: the connector's environment; `now`: epoch milliseconds
+ *   (used only when a result's `verifiedAt` is not a date).
+ * @public
+ */
+declare function mergeClaim(previous: unknown, event: MergeEvent, opts: {
+    env: "live" | "sandbox";
+    now?: () => number;
+}): MergeOutcome;
+
+/**
+ * The gate: a claim and a policy in, `{ ok }` or a reason and an action out
+ * (spec 2026-10-29 §5.3). Pure and framework-free; edge-runtime safe.
+ */
+
+/**
+ * What a route requires of the person's claim.
+ * @public
+ */
+interface GatePolicy {
+    /** The lowest level that passes. */
+    level: 1 | 2 | 3;
+    /** Maximum age of `verified_at`, in days. */
+    maxAgeDays?: number;
+    /** Maximum age of `rechecked_at` (falling back to `verified_at` when absent), in minutes. */
+    maxRecheckAgeMinutes?: number;
+    /** The assurances that pass; any when omitted. */
+    assurance?: string[];
+    /** The environment that passes; any when omitted. */
+    env?: "live" | "sandbox";
+    /** Flags that block. Default `["revoked", "face_mismatch"]`. */
+    denyFlags?: ClaimFlag[];
+}
+/** Why a gate failed. @public */
+type GateReason = "no_claim" | "unsupported_version" | "wrong_env" | "flagged" | "level_too_low" | "stale" | "recheck_stale" | "assurance_not_allowed";
+/**
+ * What the app should do about a failed gate: start a verification
+ * (`verify`), a step-up (`step_up`), a re-check (`recheck`), or refuse
+ * (`block`).
+ * @public
+ */
+type GateAction = "verify" | "step_up" | "recheck" | "block";
+/** Result of {@link evaluateGate}. @public */
+type GateResult = {
+    ok: true;
+    claim: SekyroClaim;
+} | {
+    ok: false;
+    reason: GateReason;
+    action: GateAction;
+    claim: SekyroClaim | null;
+};
+/**
+ * Check a claim (as read from the session token, an object or its JSON
+ * string) against a policy. The checks run in this order: present, version,
+ * environment, flags, level, age, re-check age, assurance.
+ *
+ * @param claim - The claim value, or anything else (`no_claim`).
+ * @param policy - What the route requires.
+ * @param nowSec - Unix seconds. Default the current time.
+ * @public
+ */
+declare function evaluateGate(claim: unknown, policy: GatePolicy, nowSec?: number): GateResult;
+
+/**
+ * The connector's small state: delivery and token ids already handled (a
+ * retry is skipped) and, optionally, which user a subject belongs to (to
+ * resolve a `subject.deleted` that carries no external references).
+ * @public
+ */
+interface ConnectorStore {
+    /** Record `id` for `ttlSec`; resolves `true` when it was already recorded (a retry). */
+    seen(id: string, ttlSec: number): Promise<boolean>;
+    /** Forget a recorded `id` so a retry is handled again; called when handling failed. Optional. */
+    forget?(id: string): Promise<void>;
+    setSubjectUser?(subjectId: string, userId: string): Promise<void>;
+    getSubjectUser?(subjectId: string): Promise<string | undefined>;
+}
+/**
+ * The in-process store of {@link memoryStore}. Its content is lost on restart
+ * and not shared between processes; use your own {@link ConnectorStore} (a
+ * cache or a table) when you run several instances.
+ * @public
+ */
+interface MemoryStore extends ConnectorStore {
+    forget(id: string): Promise<void>;
+    setSubjectUser(subjectId: string, userId: string): Promise<void>;
+    getSubjectUser(subjectId: string): Promise<string | undefined>;
+    /** The number of recorded ids not yet expired. */
+    size(): number;
+}
+/**
+ * An in-memory {@link ConnectorStore}, the connector's default. Expired ids
+ * are evicted on every call, so it never grows past the ids of one TTL window.
+ * @param opts - `now`: a clock returning epoch milliseconds (default `Date.now`).
+ * @public
+ */
+declare function memoryStore(opts?: {
+    now?: () => number;
+}): MemoryStore;
+
+/**
+ * Where a provider keeps the claim. A provider package (`@sekyro/connect-zitadel`,
+ * `@sekyro/connect-supabase`, ...) ships one; any object of this shape works.
+ * @public
+ */
+interface ProviderAdapter {
+    /** The provider's name, for example `zitadel` or `supabase`. */
+    readonly name: string;
+    /** The value stored at the provider's claim key for this user, or `null`. */
+    readUser(userId: string): Promise<unknown>;
+    /** Store the claim at the provider's claim key for this user. */
+    writeUser(userId: string, claim: SekyroClaim): Promise<void>;
+    /** The value at the provider's claim path inside a decoded session token. */
+    readClaimFromToken(tokenClaims: Record<string, unknown>): unknown;
+    /**
+     * Optional read-merge-write for one user. Read the stored value, call `fn`
+     * with it, store `claim` when the outcome is `changed` and `claim` is not
+     * `null`, and resolve to the outcome. Make it atomic for the user against
+     * every other `update` the adapter can see (a per-user lock, a transaction
+     * or a compare-and-set retry; `fn` is pure and may be called again).
+     * Without it, the connector serialises `readUser` then `writeUser` per user
+     * in this process only.
+     */
+    update?(userId: string, fn: (previous: unknown) => MergeOutcome): Promise<MergeOutcome>;
+}
+/** Why a webhook was not written. @public */
+type WebhookSkipReason = "duplicate_delivery" | "ignored_event" | "other_app" | "no_external_ref" | "result_token_required" | "revocation_unresolved" | "env_mismatch" | "unsupported_version" | "stale_ignored" | "not_approved" | "no_change";
+/**
+ * Structured events of the connector, for your logger. Ids, enums and rules
+ * only: never a claim body, a token, a secret or a return URL.
+ * @public
+ */
+type ConnectorLogEvent = {
+    type: "write";
+    userId: string;
+    sessionId?: string;
+    rule: MergeRule;
+} | {
+    type: "skip";
+    reason: WebhookSkipReason;
+    sessionId?: string;
+    subjectId?: string;
+} | {
+    type: "result_token_absent";
+    sessionId: string;
+} | {
+    type: "revocation_unresolved";
+    subjectId: string;
+} | {
+    type: "env_mismatch";
+    sessionId: string;
+} | {
+    type: "flag_cleared";
+    userId: string;
+    flag: ClaimFlag;
+};
+/** Options of {@link createConnector}. @public */
+interface ConnectorOptions {
+    /** A client with this environment's API key. */
+    sekyro: Sekyro;
+    /** Your app id, or every app id this connector serves. */
+    appId: string | string[];
+    /** The environment of the API key and webhook secret; a claim from the other one is never written. */
+    env: "live" | "sandbox";
+    /** The webhook endpoint secret. */
+    webhookSecret: string;
+    /** Where the claim is stored. */
+    provider: ProviderAdapter;
+    /** What {@link Connector.userDeleted} does with the person's subjects. Default `ignore`. */
+    onUserDeleted?: "ignore" | "revoke" | "delete";
+    /** Delivery de-duplication and the subject-to-user map. Default {@link memoryStore}. */
+    store?: ConnectorStore;
+    /** Refuse to write a terminal webhook without a result token. Default `false`. */
+    requireResultToken?: boolean;
+    /** Passed to `verifyResultToken`. */
+    issuer?: string;
+    /** Passed to `verifyResultToken`. */
+    jwksUrl?: string;
+    /** `fetch` for the result-token key set. Default `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /** Clock returning epoch milliseconds. Default `Date.now`. */
+    now?: () => number;
+    /** Receives every {@link ConnectorLogEvent}; the connector never writes to the console. */
+    logger?: (event: ConnectorLogEvent) => void;
+}
+/** Result of {@link Connector.webhook}. @public */
+type WebhookOutcome = {
+    handled: true;
+    event: WebhookEventType;
+    userId: string;
+    claim: SekyroClaim | null;
+    rule: MergeRule;
+} | {
+    handled: false;
+    event: WebhookEventType | null;
+    reason: WebhookSkipReason;
+};
+/** Options of {@link Connector.start}, {@link Connector.recheck} and {@link Connector.stepUp}. @public */
+interface StartOptions {
+    /** A flow slug or id; the app's default flow when omitted. */
+    flow?: string;
+    locale?: Locale;
+    /** Where the hosted flow sends the person at the end. */
+    returnUrl?: string;
+    /** A value you store against the user and check on the return. */
+    state?: string;
+    ttlMinutes?: number;
+}
+/** The object {@link createConnector} returns. @public */
+interface Connector {
+    /** The environment the connector writes claims for. */
+    readonly env: "live" | "sandbox";
+    /** The app ids whose webhooks and result tokens the connector accepts. */
+    readonly appIds: readonly string[];
+    /**
+     * Verify and apply a Sekyro webhook. Pass the raw body exactly as received.
+     * Throws `SekyroWebhookError` (bad signature), `SekyroResultTokenError` (bad
+     * token) or {@link SekyroConnectError} (token for another session or user):
+     * answer those with a 4xx, except `SekyroConnectError` with code
+     * `unavailable` (the key set could not be fetched): answer it with a 503 so
+     * Sekyro retries. Answer 2xx once it resolves.
+     */
+    webhook(rawBody: string, headers: Headers | Record<string, string | string[] | undefined>): Promise<WebhookOutcome>;
+    /**
+     * The return-URL path: read the session and its signed result token with
+     * the API key, verify the token (audience = your app ids, environment) and
+     * apply it. A session created without an app or for another app is refused
+     * (`SekyroResultTokenError` `wrong_audience`), as is a session of another
+     * user ({@link SekyroConnectError} `external_ref_mismatch`). Check your
+     * `state` first: store the session id with the state when you create the
+     * session, and compare both on the return.
+     */
+    sync(userId: string, sessionId: string): Promise<{
+        claim: SekyroClaim | null;
+        rule: MergeRule;
+    }>;
+    /** Create a verification session for your user (`subject.externalRef` = `userId`). */
+    start(userId: string, opts?: StartOptions): Promise<CreatedSession>;
+    /** Create a re-check session for your user's subject. */
+    recheck(userId: string, opts?: Omit<StartOptions, "flow">): Promise<CreatedSession>;
+    /** Create a step-up session for your user's subject with an identity flow. */
+    stepUp(userId: string, opts: StartOptions & {
+        flow: string;
+    }): Promise<CreatedSession>;
+    /** Your app deleted the user: apply the `onUserDeleted` policy to the person's subjects. */
+    userDeleted(userId: string): Promise<{
+        policy: "ignore" | "revoke" | "delete";
+        subjects: number;
+    }>;
+    /** The stored claim, read from the provider (no token lag). */
+    claimOf(userId: string): Promise<SekyroClaim | null>;
+    /** Remove a flag from the stored claim (for example after a manual review of a `face_mismatch`). */
+    clearFlag(userId: string, flag: ClaimFlag): Promise<SekyroClaim | null>;
+    /** Check a decoded session token against a policy; `env` defaults to the connector's. */
+    gate(tokenClaims: Record<string, unknown>, policy: GatePolicy): GateResult;
+}
+/**
+ * Tie Sekyro to an auth provider: verified webhooks and return-URL reads
+ * become one idempotent claim write on the provider's user, and the gate
+ * reads that claim from the session token.
+ *
+ * @example
+ * ```ts
+ * const connector = createConnector({
+ *   sekyro: new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! }),
+ *   appId: process.env.SEKYRO_APP_ID!,
+ *   env: "live",
+ *   webhookSecret: process.env.SEKYRO_WEBHOOK_SECRET!,
+ *   provider,
+ * });
+ * ```
+ * @public
+ */
+declare function createConnector(opts: ConnectorOptions): Connector;
+
+export { type Connector as C, type GatePolicy as G, type MemoryStore as M, type ProviderAdapter as P, type SekyroClaim as S, type VerificationResultInput as V, type WebhookOutcome as W, type GateResult as a, CLAIM_VERSION as b, type ClaimFlag as c, type ConnectorLogEvent as d, type ConnectorOptions as e, type ConnectorStore as f, type GateAction as g, type GateReason as h, type MergeEvent as i, type MergeOutcome as j, type MergeRule as k, type StartOptions as l, type WebhookSkipReason as m, createConnector as n, evaluateGate as o, memoryStore as p, mergeClaim as q, parseClaim as r };