@atlasauth/backend 0.2.0 → 0.5.0

package/dist/client/messaging.d.ts

@@ -1,30 +1,235 @@
 import { type RequestFn } from './request';
 /**
- * §BYOK messaging provider config — wire the tenant's own email/SMS provider
- * (Resend/SES/SMTP/Brevo/Mailgun, Twilio) over the secret-key BAPI.
+ * Messaging providers — wire your own email or SMS provider (Resend, SES, SMTP,
+ * Brevo, Mailgun; Twilio, Vonage, MessageBird, Plivo, Telnyx, Sinch, Infobip,
+ * ClickSend, Bandwidth, AWS SNS) over the secret-key Backend API.
+ *
+ * Each transport accepts an exact set of `config` keys; the API refuses an
+ * unknown key with a 422 naming `config.<key>`. These types mirror that schema,
+ * so a typo or another provider's key name fails to compile.
  *
  * A provider SECRET is WRITE-ONLY: it goes in through `config` and is never
  * read back — a response reports only WHICH secret keys are set (`secrets_set`).
- * Omit a secret on an edit to keep the stored one (so a from-address change need
- * not re-enter the API key).
+ *
+ * Required keys: every key marked "Required on first setup" must be sent the
+ * first time you configure a transport (or when you switch the channel to a
+ * different transport). When you update the SAME transport, the stored config is
+ * kept: omit a key — or send it as `''` — and its stored value (including a
+ * stored secret) stays. So a from-address change need not re-enter the API key.
  */
-export interface MessagingProvider {
-    object: 'messaging_provider';
-    channel: 'email' | 'sms';
-    transport: string;
-    from_address: string | null;
-    status: string;
-    /** Non-secret config only — secret values are stripped before serialising. */
-    config: Record<string, unknown>;
-    /** Which secret keys are set for this transport, never their values. */
-    secrets_set: Record<string, boolean>;
-    updated_at: number;
+/** Email transports accepted by `PUT /v1/messaging_providers/email`. */
+export type EmailTransport = 'resend' | 'ses' | 'smtp' | 'brevo' | 'mailgun';
+/** SMS transports accepted by `PUT /v1/messaging_providers/sms`. */
+export type SmsTransport = 'twilio' | 'vonage' | 'messagebird' | 'plivo' | 'telnyx' | 'sinch' | 'infobip' | 'clicksend' | 'bandwidth' | 'aws_sns';
+export type MessagingTransport = EmailTransport | SmsTransport;
+/** Sender number or ID for an SMS provider. `from_address` on the request takes precedence. */
+interface SmsFrom {
+    /** Sender number or ID for this provider. Optional; `from_address` on the request takes precedence. */
+    from?: string;
 }
-export interface MessagingProviders {
-    object: 'messaging_providers';
-    email: MessagingProvider | null;
-    sms: MessagingProvider | null;
+/** Resend. */
+export interface ResendConfig {
+    /** Resend API key (`re_…`). Required on first setup. Write-only: never returned. */
+    api_key: string;
+}
+/** Brevo. */
+export interface BrevoConfig {
+    /** Brevo API key (`xkeysib-…`). Required on first setup. Write-only: never returned. */
+    api_key: string;
+}
+/** Mailgun. */
+export interface MailgunConfig {
+    /** Mailgun private API key. Required on first setup. Write-only: never returned. */
+    api_key: string;
+    /** Your Mailgun sending domain, e.g. `mg.example.com`. Required on first setup. */
+    domain: string;
+    /** Mailgun region. Default `us`. */
+    region?: 'us' | 'eu';
+}
+/** Amazon SES. */
+export interface SesConfig {
+    /** AWS region, e.g. `us-east-1`. Required on first setup. */
+    region: string;
+    /** IAM access key ID. Required on first setup. Write-only: never returned. */
+    access_key_id: string;
+    /** IAM secret access key. Required on first setup. Write-only: never returned. */
+    secret_access_key: string;
+    /** STS session token, only for temporary credentials. Write-only: never returned. */
+    session_token?: string;
+}
+/** Any SMTP server. */
+export interface SmtpConfig {
+    /** SMTP server hostname, e.g. `smtp.example.com`. Required on first setup. */
+    host: string;
+    /** SMTP port (1-65535). Default 587. */
+    port?: number;
+    /** Use implicit TLS. Default: `true` on port 465, otherwise STARTTLS. */
+    secure?: boolean;
+    /** SMTP username, if the server requires authentication. */
+    username?: string;
+    /** SMTP password or app password. Write-only: never returned. */
+    password?: string;
+}
+/** Twilio. */
+export interface TwilioConfig extends SmsFrom {
+    /** Twilio Account SID (`AC…`). Required on first setup. */
+    account_sid: string;
+    /** Twilio auth token. Required on first setup. Write-only: never returned. */
+    auth_token: string;
+    /** WhatsApp-enabled sender number, for the WhatsApp channel. */
+    whatsapp_from?: string;
+    /** Voice-capable number, for the voice channel. */
+    voice_from?: string;
+}
+/** Vonage. */
+export interface VonageConfig extends SmsFrom {
+    /** Vonage API key. Required on first setup. */
+    api_key: string;
+    /** Vonage API secret. Required on first setup. Write-only: never returned. */
+    api_secret: string;
+}
+/** MessageBird (Bird). */
+export interface MessagebirdConfig extends SmsFrom {
+    /** MessageBird (Bird) access key. Required on first setup. Write-only: never returned. */
+    access_key: string;
+}
+/** Plivo. */
+export interface PlivoConfig extends SmsFrom {
+    /** Plivo Auth ID. Required on first setup. */
+    auth_id: string;
+    /** Plivo auth token. Required on first setup. Write-only: never returned. */
+    auth_token: string;
+}
+/** Telnyx. */
+export interface TelnyxConfig extends SmsFrom {
+    /** Telnyx API key. Required on first setup. Write-only: never returned. */
+    api_key: string;
+}
+/** Sinch. */
+export interface SinchConfig extends SmsFrom {
+    /** Sinch service plan ID. Required on first setup. */
+    service_plan_id: string;
+    /** Sinch API token. Required on first setup. Write-only: never returned. */
+    api_token: string;
+    /** Sinch API region, a short lowercase code such as `us` or `eu`. Default `us`. */
+    region?: string;
+}
+/** Infobip. */
+export interface InfobipConfig extends SmsFrom {
+    /** Your Infobip base URL, e.g. `https://xxxxx.api.infobip.com`. Must be https. Required on first setup. */
+    base_url: string;
+    /** Infobip API key. Required on first setup. Write-only: never returned. */
+    api_key: string;
+}
+/** ClickSend. */
+export interface ClicksendConfig extends SmsFrom {
+    /** ClickSend username (your login email). Required on first setup. */
+    username: string;
+    /** ClickSend API key. Required on first setup. Write-only: never returned. */
+    api_key: string;
+}
+/** Bandwidth. */
+export interface BandwidthConfig extends SmsFrom {
+    /** Bandwidth account ID. Required on first setup. */
+    account_id: string;
+    /** Bandwidth messaging application ID. Required on first setup. */
+    application_id: string;
+    /** Bandwidth API username. Required on first setup. */
+    username: string;
+    /** Bandwidth API password. Required on first setup. Write-only: never returned. */
+    password: string;
+}
+/** Amazon SNS. */
+export interface AwsSnsConfig extends SmsFrom {
+    /** AWS region, e.g. `us-east-1`. Required on first setup. */
+    region: string;
+    /** IAM access key ID. Required on first setup. */
+    access_key_id: string;
+    /** IAM secret access key. Required on first setup. Write-only: never returned. */
+    secret_access_key: string;
+    /** STS session token, only for temporary credentials. Write-only: never returned. */
+    session_token?: string;
+}
+/** The `config` shape for each transport, keyed by transport. */
+export interface MessagingTransportConfigs {
+    resend: ResendConfig;
+    ses: SesConfig;
+    smtp: SmtpConfig;
+    brevo: BrevoConfig;
+    mailgun: MailgunConfig;
+    twilio: TwilioConfig;
+    vonage: VonageConfig;
+    messagebird: MessagebirdConfig;
+    plivo: PlivoConfig;
+    telnyx: TelnyxConfig;
+    sinch: SinchConfig;
+    infobip: InfobipConfig;
+    clicksend: ClicksendConfig;
+    bandwidth: BandwidthConfig;
+    aws_sns: AwsSnsConfig;
 }
+/** The write-only (secret) keys of each transport — never present in a response. */
+export interface MessagingSecretKeys {
+    resend: 'api_key';
+    ses: 'access_key_id' | 'secret_access_key' | 'session_token';
+    smtp: 'password';
+    brevo: 'api_key';
+    mailgun: 'api_key';
+    twilio: 'auth_token';
+    vonage: 'api_secret';
+    messagebird: 'access_key';
+    plivo: 'auth_token';
+    telnyx: 'api_key';
+    sinch: 'api_token';
+    infobip: 'api_key';
+    clicksend: 'api_key';
+    bandwidth: 'password';
+    aws_sns: 'secret_access_key' | 'session_token';
+}
+interface ProviderBodyBase<T extends MessagingTransport> {
+    transport: T;
+    /**
+     * Email: the From address, e.g. `"Acme <no-reply@acme.com>"` — a sender your
+     * provider accepts. SMS: the sender number in E.164 format, e.g. `+15551234567`.
+     */
+    from_address?: string;
+}
+/**
+ * First setup of transport `T` (or a switch to it): `config` carries every
+ * required key.
+ */
+export interface MessagingProviderSetup<T extends MessagingTransport> extends ProviderBodyBase<T> {
+    config: MessagingTransportConfigs[T];
+}
+/**
+ * An update of the transport already configured on the channel: every `config`
+ * key is optional. An omitted (or `''`) key keeps its stored value — including a
+ * stored secret.
+ */
+export interface MessagingProviderUpdate<T extends MessagingTransport> extends ProviderBodyBase<T> {
+    config?: Partial<MessagingTransportConfigs[T]>;
+}
+/** Body for `messaging.setEmail` — discriminated by `transport`. */
+export type EmailProviderInput = {
+    [T in EmailTransport]: MessagingProviderSetup<T> | MessagingProviderUpdate<T>;
+}[EmailTransport];
+/** Body for `messaging.setSms` — discriminated by `transport`. */
+export type SmsProviderInput = {
+    [T in SmsTransport]: MessagingProviderSetup<T> | MessagingProviderUpdate<T>;
+}[SmsTransport];
+/** First-setup body for the email channel. Use with `satisfies` to require every required key. */
+export type EmailProviderSetup = {
+    [T in EmailTransport]: MessagingProviderSetup<T>;
+}[EmailTransport];
+/** First-setup body for the SMS channel. Use with `satisfies` to require every required key. */
+export type SmsProviderSetup = {
+    [T in SmsTransport]: MessagingProviderSetup<T>;
+}[SmsTransport];
+/**
+ * @deprecated The untyped body accepted before per-transport typing. Use
+ * {@link EmailProviderInput} / {@link SmsProviderInput} instead; the API refuses
+ * any `config` key the transport does not use.
+ */
 export interface MessagingProviderInput {
     /** The transport, e.g. `resend`, `ses`, `smtp` (email) or `twilio` (sms). */
     transport: string;
@@ -32,6 +237,42 @@ export interface MessagingProviderInput {
     /** Transport config; carries the write-only secret keys on write. */
     config?: Record<string, unknown>;
 }
+/** The non-secret config keys of transport `T`. */
+type PublicConfigKey<T extends MessagingTransport> = Exclude<keyof MessagingTransportConfigs[T], MessagingSecretKeys[T]>;
+/**
+ * A configured provider as returned by the API. `config` holds the non-secret
+ * settings only (values come back as strings, e.g. `port: "587"`); secrets are
+ * never returned — `secrets_set` says which ones are stored.
+ */
+export interface MessagingProviderOf<C extends 'email' | 'sms', T extends MessagingTransport> {
+    object: 'messaging_provider';
+    channel: C;
+    transport: T;
+    from_address: string | null;
+    status: string;
+    /** Non-secret config only — secret values are never returned. */
+    config: {
+        [K in PublicConfigKey<T>]?: string;
+    };
+    /** For each secret key of this transport: whether a value is stored. Never the value. */
+    secrets_set: {
+        [K in MessagingSecretKeys[T]]: boolean;
+    };
+    updated_at: number;
+}
+export type EmailProvider = {
+    [T in EmailTransport]: MessagingProviderOf<'email', T>;
+}[EmailTransport];
+export type SmsProvider = {
+    [T in SmsTransport]: MessagingProviderOf<'sms', T>;
+}[SmsTransport];
+/** Either channel's provider. Narrow on `transport` (or `channel`) to read its config. */
+export type MessagingProvider = EmailProvider | SmsProvider;
+export interface MessagingProviders {
+    object: 'messaging_providers';
+    email: EmailProvider | null;
+    sms: SmsProvider | null;
+}
 export interface MessagingTestResult {
     object: 'messaging_test';
     channel: string;
@@ -43,14 +284,39 @@ export interface DeletedMessagingProvider {
     channel: string;
     deleted: true;
 }
+/**
+ * The deprecated untyped body, accepted only when `transport` is a plain
+ * `string` (not a known literal) — so a typed literal with a wrong key still
+ * fails to compile instead of falling through to the legacy overload.
+ */
+type LegacyInput<T extends string> = Omit<MessagingProviderInput, 'transport'> & {
+    transport: T;
+} & (string extends T ? unknown : never);
 export declare function messagingResource(request: RequestFn): {
     /** The instance's configured email and SMS providers, secrets omitted. */
     get(): Promise<MessagingProviders>;
-    setEmail(body: MessagingProviderInput): Promise<MessagingProvider>;
-    setSms(body: MessagingProviderInput): Promise<MessagingProvider>;
+    /**
+     * Configure (or update) the email provider. `config` keys are checked per
+     * `transport`; on an update of the same transport, omitted keys — including
+     * secrets — keep their stored values.
+     */
+    setEmail: {
+        (body: EmailProviderInput): Promise<EmailProvider>;
+        <T extends string>(body: LegacyInput<T>): Promise<MessagingProvider>;
+    };
+    /**
+     * Configure (or update) the SMS provider. `config` keys are checked per
+     * `transport`; on an update of the same transport, omitted keys — including
+     * secrets — keep their stored values.
+     */
+    setSms: {
+        (body: SmsProviderInput): Promise<SmsProvider>;
+        <T extends string>(body: LegacyInput<T>): Promise<MessagingProvider>;
+    };
     deleteChannel(channel: "email" | "sms"): Promise<DeletedMessagingProvider>;
     /** Send a fixed, clearly-marked test message through the channel's provider. */
     test(channel: "email" | "sms", body: {
         to: string;
     }): Promise<MessagingTestResult>;
 };
+export {};

package/dist/client/messaging.js

@@ -3,17 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.messagingResource = messagingResource;
 const request_1 = require("./request");
 function messagingResource(request) {
+    function setEmail(body) {
+        return request({ method: 'PUT', path: '/v1/messaging_providers/email', body });
+    }
+    function setSms(body) {
+        return request({ method: 'PUT', path: '/v1/messaging_providers/sms', body });
+    }
     return {
         /** The instance's configured email and SMS providers, secrets omitted. */
         get() {
             return request({ method: 'GET', path: '/v1/messaging_providers' });
         },
-        setEmail(body) {
-            return request({ method: 'PUT', path: '/v1/messaging_providers/email', body });
-        },
-        setSms(body) {
-            return request({ method: 'PUT', path: '/v1/messaging_providers/sms', body });
-        },
+        /**
+         * Configure (or update) the email provider. `config` keys are checked per
+         * `transport`; on an update of the same transport, omitted keys — including
+         * secrets — keep their stored values.
+         */
+        setEmail,
+        /**
+         * Configure (or update) the SMS provider. `config` keys are checked per
+         * `transport`; on an update of the same transport, omitted keys — including
+         * secrets — keep their stored values.
+         */
+        setSms,
         deleteChannel(channel) {
             return request({ method: 'DELETE', path: `/v1/messaging_providers/${(0, request_1.enc)(channel)}` });
         },

package/dist/client/messaging.js.map

@@ -1 +1 @@
-{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../src/client/messaging.ts"],"names":[],"mappings":";;AAmDA,8CAwBC;AA3ED,uCAAgD;AAmDhD,SAAgB,iBAAiB,CAAC,OAAkB;IAClD,OAAO;QACL,0EAA0E;QAC1E,GAAG;YACD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,yBAAyB,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,QAAQ,CAAC,IAA4B;YACnC,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,+BAA+B,EAAE,IAAI,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,CAAC,IAA4B;YACjC,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,aAAa,CAAC,OAAwB;YACpC,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,2BAA2B,IAAA,aAAG,EAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,gFAAgF;QAChF,IAAI,CAAC,OAAwB,EAAE,IAAoB;YACjD,OAAO,OAAO,CAAC;gBACb,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,2BAA2B,IAAA,aAAG,EAAC,OAAO,CAAC,OAAO;gBACpD,IAAI;aACL,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"messaging.js","sourceRoot":"","sources":["../../src/client/messaging.ts"],"names":[],"mappings":";;AAsVA,8CA4CC;AAlYD,uCAAgD;AAsVhD,SAAgB,iBAAiB,CAAC,OAAkB;IAIlD,SAAS,QAAQ,CAAC,IAAa;QAC7B,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,+BAA+B,EAAE,IAAI,EAAE,CAAC,CAAC;IACjF,CAAC;IAKD,SAAS,MAAM,CAAC,IAAa;QAC3B,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO;QACL,0EAA0E;QAC1E,GAAG;YACD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,yBAAyB,EAAE,CAAC,CAAC;QACrE,CAAC;QACD;;;;WAIG;QACH,QAAQ;QACR;;;;WAIG;QACH,MAAM;QACN,aAAa,CAAC,OAAwB;YACpC,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,2BAA2B,IAAA,aAAG,EAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,gFAAgF;QAChF,IAAI,CAAC,OAAwB,EAAE,IAAoB;YACjD,OAAO,OAAO,CAAC;gBACb,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,2BAA2B,IAAA,aAAG,EAAC,OAAO,CAAC,OAAO;gBACpD,IAAI;aACL,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/discovery.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OIDC discovery of an instance's JWKS URL, so `new AtlasBackend({ issuer })`
+ * works without a `jwksUrl`.
+ *
+ * Where the document lives:
+ *   - an instance with its own frontend API host (every instance created from
+ *     the dashboard): `${issuer}/.well-known/openid-configuration`;
+ *   - an instance on the SHARED host: its tokens carry the shared issuer, and the
+ *     shared host's root discovery document describes a different instance's key
+ *     set. Such an instance must name itself (`instanceId`, or a `publishableKey`
+ *     it is derived from) so discovery uses the per-instance document at
+ *     `${issuer}/instances/${instanceId}/.well-known/openid-configuration`.
+ *
+ * Caching mirrors the JWKS cache: the discovered URL is reused for the JWKS TTL
+ * (an hour), a failed refresh keeps serving the last good URL, and a failing
+ * endpoint is retried at most once a minute — so a broken or hostile discovery
+ * endpoint cannot turn verification traffic into outbound request floods.
+ */
+export declare class DiscoveryError extends Error {
+    constructor(message: string);
+}
+export interface JwksDiscoveryDeps {
+    /** The `iss` tokens carry. The discovery document's `issuer` must equal it. */
+    issuer: string;
+    /** Per-instance discovery for shared-host instances. */
+    instanceId?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    ttlMs?: number;
+    refetchIntervalMs?: number;
+}
+/** The instance id inside a publishable key (`pk_live_ins_…` / `pk_test_ins_…`), if it has one. */
+export declare function instanceIdFromPublishableKey(publishableKey: string): string | undefined;
+/** The discovery document URL for an issuer (and optional instance id). */
+export declare function discoveryUrlFor(issuer: string, instanceId?: string): string;
+export declare class JwksDiscovery {
+    private readonly deps;
+    readonly url: string;
+    private cachedUri;
+    private fetchedAt;
+    private lastAttemptAt;
+    private lastError;
+    private inflight;
+    constructor(deps: JwksDiscoveryDeps);
+    private get now();
+    /** The JWKS URL, from cache when fresh. Throws {@link DiscoveryError} when none can be had. */
+    jwksUri(): Promise<string>;
+    private fetchUri;
+}

package/dist/discovery.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwksDiscovery = exports.DiscoveryError = void 0;
+exports.instanceIdFromPublishableKey = instanceIdFromPublishableKey;
+exports.discoveryUrlFor = discoveryUrlFor;
+const jwks_cache_1 = require("./jwks-cache");
+/**
+ * OIDC discovery of an instance's JWKS URL, so `new AtlasBackend({ issuer })`
+ * works without a `jwksUrl`.
+ *
+ * Where the document lives:
+ *   - an instance with its own frontend API host (every instance created from
+ *     the dashboard): `${issuer}/.well-known/openid-configuration`;
+ *   - an instance on the SHARED host: its tokens carry the shared issuer, and the
+ *     shared host's root discovery document describes a different instance's key
+ *     set. Such an instance must name itself (`instanceId`, or a `publishableKey`
+ *     it is derived from) so discovery uses the per-instance document at
+ *     `${issuer}/instances/${instanceId}/.well-known/openid-configuration`.
+ *
+ * Caching mirrors the JWKS cache: the discovered URL is reused for the JWKS TTL
+ * (an hour), a failed refresh keeps serving the last good URL, and a failing
+ * endpoint is retried at most once a minute — so a broken or hostile discovery
+ * endpoint cannot turn verification traffic into outbound request floods.
+ */
+class DiscoveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DiscoveryError';
+    }
+}
+exports.DiscoveryError = DiscoveryError;
+const stripSlash = (value) => value.replace(/\/+$/, '');
+/** The instance id inside a publishable key (`pk_live_ins_…` / `pk_test_ins_…`), if it has one. */
+function instanceIdFromPublishableKey(publishableKey) {
+    const match = /^pk_(?:live|test)_(ins_[A-Za-z0-9]+)$/.exec(publishableKey.trim());
+    return match?.[1];
+}
+/** The discovery document URL for an issuer (and optional instance id). */
+function discoveryUrlFor(issuer, instanceId) {
+    const base = stripSlash(issuer);
+    return instanceId
+        ? `${base}/instances/${encodeURIComponent(instanceId)}/.well-known/openid-configuration`
+        : `${base}/.well-known/openid-configuration`;
+}
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+class JwksDiscovery {
+    deps;
+    url;
+    cachedUri = null;
+    fetchedAt = 0;
+    lastAttemptAt = 0;
+    lastError = null;
+    inflight = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.url = discoveryUrlFor(deps.issuer, deps.instanceId);
+    }
+    get now() {
+        return (this.deps.now ?? Date.now)();
+    }
+    /** The JWKS URL, from cache when fresh. Throws {@link DiscoveryError} when none can be had. */
+    async jwksUri() {
+        const now = this.now;
+        const ttl = this.deps.ttlMs ?? jwks_cache_1.DEFAULT_TTL_MS;
+        const interval = this.deps.refetchIntervalMs ?? jwks_cache_1.REFETCH_INTERVAL_MS;
+        if (this.cachedUri && now - this.fetchedAt < ttl)
+            return this.cachedUri;
+        // Throttle: inside the retry window, answer from what we have (or the last error).
+        if (this.lastAttemptAt && now - this.lastAttemptAt < interval) {
+            if (this.cachedUri)
+                return this.cachedUri;
+            if (this.lastError)
+                throw this.lastError;
+        }
+        if (this.inflight)
+            return this.inflight;
+        this.lastAttemptAt = now;
+        this.inflight = this.fetchUri()
+            .then((uri) => {
+            this.cachedUri = uri;
+            this.fetchedAt = now;
+            this.lastError = null;
+            return uri;
+        })
+            .catch((error) => {
+            this.lastError =
+                error instanceof DiscoveryError
+                    ? error
+                    : new DiscoveryError(`OIDC discovery at ${this.url} failed: ${error?.message ?? String(error)}`);
+            // Keep serving the last good URL through a discovery outage.
+            if (this.cachedUri)
+                return this.cachedUri;
+            throw this.lastError;
+        })
+            .finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    async fetchUri() {
+        const fail = (why) => new DiscoveryError(`OIDC discovery at ${this.url} failed: ${why}. Pass \`jwksUrl\` explicitly` +
+            (this.deps.instanceId
+                ? '.'
+                : ', or — for an instance without its own frontend API domain — pass `instanceId` (or `publishableKey`).'));
+        const response = await (this.deps.fetchImpl ?? fetch)(this.url, {
+            headers: { accept: 'application/json' },
+        });
+        if (!response.ok)
+            throw fail(`HTTP ${response.status}`);
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            throw fail('the response is not JSON');
+        }
+        const doc = body;
+        if (!doc || typeof doc !== 'object')
+            throw fail('the response is not a discovery document');
+        // OIDC Discovery §4.3: the document's issuer MUST match the issuer it was
+        // fetched for — otherwise its keys belong to someone else.
+        if (typeof doc.issuer !== 'string' || stripSlash(doc.issuer) !== stripSlash(this.deps.issuer)) {
+            throw fail(`its issuer (${String(doc.issuer)}) does not match the configured issuer (${this.deps.issuer})`);
+        }
+        if (typeof doc.jwks_uri !== 'string')
+            throw fail('it has no jwks_uri');
+        let jwks;
+        try {
+            jwks = new URL(doc.jwks_uri);
+        }
+        catch {
+            throw fail('its jwks_uri is not an absolute URL');
+        }
+        if (jwks.protocol !== 'https:' && !(jwks.protocol === 'http:' && isLoopback(jwks.hostname))) {
+            throw fail('its jwks_uri is not https');
+        }
+        return jwks.toString();
+    }
+}
+exports.JwksDiscovery = JwksDiscovery;
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

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

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './jwks-cache';
+export { DiscoveryError, JwksDiscovery, discoveryUrlFor, instanceIdFromPublishableKey } from './discovery';
 export * from './verify';
 export * from './handshake';
 export * from './webhooks';
@@ -7,3 +8,7 @@ export type { AtlasClient } from './client';
 export * from './client';
 export { createTestIssuer } from './testing';
 export type { TestIssuer, CreateTestIssuerOptions } from './testing';
+export { verifyPCActn } from './pca/verify';
+export type { PcaVerdict, PcaContext, VerifyPCActnOptions } from './pca/verify';
+export { requirePCA, defaultExtract, memoryPcaStore } from './pca/require-pca';
+export type { RequirePcaOptions, PcaGuardResult, PcaRequestLike, PcaStateStore } from './pca/require-pca';

package/dist/index.js

@@ -14,9 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTestIssuer = exports.createAtlasClient = void 0;
+exports.memoryPcaStore = exports.defaultExtract = exports.requirePCA = exports.verifyPCActn = exports.createTestIssuer = exports.createAtlasClient = exports.instanceIdFromPublishableKey = exports.discoveryUrlFor = exports.JwksDiscovery = exports.DiscoveryError = void 0;
 // §7.3 token verification — the original surface, unchanged.
 __exportStar(require("./jwks-cache"), exports);
+// OIDC discovery of the JWKS URL when only `issuer` is configured.
+var discovery_1 = require("./discovery");
+Object.defineProperty(exports, "DiscoveryError", { enumerable: true, get: function () { return discovery_1.DiscoveryError; } });
+Object.defineProperty(exports, "JwksDiscovery", { enumerable: true, get: function () { return discovery_1.JwksDiscovery; } });
+Object.defineProperty(exports, "discoveryUrlFor", { enumerable: true, get: function () { return discovery_1.discoveryUrlFor; } });
+Object.defineProperty(exports, "instanceIdFromPublishableKey", { enumerable: true, get: function () { return discovery_1.instanceIdFromPublishableKey; } });
 __exportStar(require("./verify"), exports);
 __exportStar(require("./handshake"), exports);
 // §12.2 inbound webhook verification for consumers.
@@ -30,4 +36,12 @@ __exportStar(require("./client"), exports);
 // Its own module, so it never sits on the hot verification path.
 var testing_1 = require("./testing");
 Object.defineProperty(exports, "createTestIssuer", { enumerable: true, get: function () { return testing_1.createTestIssuer; } });
+// Proof-Carrying Authority (agentic auth): offline verifier + framework-agnostic guard,
+// beside the session-token verifier above.
+var verify_1 = require("./pca/verify");
+Object.defineProperty(exports, "verifyPCActn", { enumerable: true, get: function () { return verify_1.verifyPCActn; } });
+var require_pca_1 = require("./pca/require-pca");
+Object.defineProperty(exports, "requirePCA", { enumerable: true, get: function () { return require_pca_1.requirePCA; } });
+Object.defineProperty(exports, "defaultExtract", { enumerable: true, get: function () { return require_pca_1.defaultExtract; } });
+Object.defineProperty(exports, "memoryPcaStore", { enumerable: true, get: function () { return require_pca_1.memoryPcaStore; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,2CAAyB;AACzB,8CAA4B;AAE5B,oDAAoD;AACpD,6CAA2B;AAE3B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB;AAEzB,yEAAyE;AACzE,2EAA2E;AAC3E,iEAAiE;AACjE,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,mEAAmE;AACnE,yCAA2G;AAAlG,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,yHAAA,4BAA4B,OAAA;AACrF,2CAAyB;AACzB,8CAA4B;AAE5B,oDAAoD;AACpD,6CAA2B;AAE3B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB;AAEzB,yEAAyE;AACzE,2EAA2E;AAC3E,iEAAiE;AACjE,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA;AAGzB,wFAAwF;AACxF,2CAA2C;AAC3C,uCAA4C;AAAnC,sGAAA,YAAY,OAAA;AAErB,iDAA+E;AAAtE,yGAAA,UAAU,OAAA;AAAE,6GAAA,cAAc,OAAA;AAAE,6GAAA,cAAc,OAAA"}

package/dist/jwks-cache.d.ts

@@ -34,6 +34,12 @@ export interface JwksCacheDeps {
      * when both are given the static set wins and no network call is ever made.
      */
     staticJwks?: Jwks;
+    /**
+     * Resolve the JWKS URL lazily (OIDC discovery) when no fixed `url` is given.
+     * Called on each fetch attempt; it does its own caching. A rejection is
+     * recorded as {@link JwksCache.lastError} and treated like a failed fetch.
+     */
+    resolveUrl?: () => Promise<string>;
     fetchImpl?: typeof fetch;
     now?: () => number;
     ttlMs?: number;
@@ -47,6 +53,8 @@ export declare class JwksCache {
     private lastAttemptAt;
     /** Exposed so a caller can assert the rate limit actually bit. */
     lastOutcome: FetchOutcome;
+    /** Why the last attempt produced no keys (e.g. a discovery failure), for diagnostics. */
+    lastError: string | null;
     constructor(deps: JwksCacheDeps);
     private get now();
     private has;