@atlasauth/backend 0.1.7 → 0.4.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/index.d.ts

@@ -7,3 +7,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,7 +14,7 @@ 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 = void 0;
 // §7.3 token verification — the original surface, unchanged.
 __exportStar(require("./jwks-cache"), exports);
 __exportStar(require("./verify"), exports);
@@ -30,4 +30,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,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/pca/require-pca.d.ts

@@ -0,0 +1,47 @@
+import { type Capability, type PCActn, type TrustBudget, type VerifyHooks } from '@atlasauth/pca';
+import { type PcaContext, type PcaVerdict } from './verify';
+/** Framework-agnostic request shape: anything with headers and (optionally) a parsed/raw body. */
+export interface PcaRequestLike {
+    headers: Record<string, string | string[] | undefined> | {
+        get(name: string): string | null;
+    };
+    body?: unknown;
+}
+/** Per-holder replay + budget state. Implement over Redis/DB; the in-memory one is for tests/single node. */
+export interface PcaStateStore {
+    get(key: string): Promise<{
+        budget?: TrustBudget;
+        lastCounter?: number;
+    } | undefined>;
+    put(key: string, state: {
+        budget?: TrustBudget;
+        lastCounter?: number;
+    }): Promise<void>;
+}
+export declare function memoryPcaStore(): PcaStateStore;
+export interface RequirePcaOptions {
+    /** Resolve the Root Intent Grant from the PCActn's `grant_ref`. null = unknown grant. */
+    resolveGrant: (grantRef: string, pcactn: PCActn) => Promise<Capability | null>;
+    hooks?: VerifyHooks;
+    extract?: (req: PcaRequestLike) => PCActn | string | null;
+    /** Anti-replay counter + budget persistence. Without it counters are not checked (surfaced in checks). */
+    budgetStore?: PcaStateStore;
+    /** Build verification context (params, plan, risk) per request. */
+    context?: (req: PcaRequestLike, pcactn: PCActn) => PcaContext | Promise<PcaContext>;
+    now?: () => number;
+    /** WWW-Authenticate realm (default "pca"). */
+    realm?: string;
+}
+export type PcaGuardResult = {
+    ok: true;
+    verdict: PcaVerdict;
+    pcactn: PCActn;
+} | {
+    ok: false;
+    status: 401 | 403;
+    verdict: PcaVerdict;
+    wwwAuthenticate?: string;
+};
+/** Default extraction: `PCA-Action: <base64url PCActn JSON>` header, else JSON body `{ pcactn }`. */
+export declare function defaultExtract(req: PcaRequestLike): PCActn | string | null;
+export declare function requirePCA(opts: RequirePcaOptions): (req: PcaRequestLike) => Promise<PcaGuardResult>;

package/dist/pca/require-pca.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryPcaStore = memoryPcaStore;
+exports.defaultExtract = defaultExtract;
+exports.requirePCA = requirePCA;
+const pca_1 = require("@atlasauth/pca");
+const verify_1 = require("./verify");
+function memoryPcaStore() {
+    const m = new Map();
+    return { get: async (k) => m.get(k), put: async (k, v) => void m.set(k, v) };
+}
+function header(req, name) {
+    const h = req.headers;
+    if (typeof h.get === 'function')
+        return h.get(name) ?? undefined;
+    const v = h[name] ?? h[name.toLowerCase()];
+    return Array.isArray(v) ? v[0] : v;
+}
+function fromB64u(s) {
+    const b = s.replace(/-/g, '+').replace(/_/g, '/');
+    return Buffer.from(b, 'base64').toString('utf8');
+}
+/** Default extraction: `PCA-Action: <base64url PCActn JSON>` header, else JSON body `{ pcactn }`. */
+function defaultExtract(req) {
+    const h = header(req, 'pca-action');
+    if (h)
+        return fromB64u(h.trim());
+    let b = req.body;
+    if (typeof b === 'string') {
+        try {
+            b = JSON.parse(b);
+        }
+        catch {
+            return null;
+        }
+    }
+    const x = b?.pcactn;
+    if (typeof x === 'string' || (x !== null && typeof x === 'object'))
+        return x;
+    return null;
+}
+const denyVerdict = (reason) => ({
+    allow: false,
+    r: 1,
+    requiredThreshold: { t: 3, proof: 'strong', optimisticAllowed: false },
+    checks: { pcactn: 'fail' },
+    reasons: [reason],
+});
+function requirePCA(opts) {
+    const realm = opts.realm ?? 'pca';
+    const challenge = (error) => `PCA realm="${realm}"${error ? `, error="${error}"` : ''}, hint="send PCA-Action: <base64url PCActn> or JSON body {pcactn}"`;
+    const unauth = (reason, error = 'invalid_request') => ({
+        ok: false,
+        status: 401,
+        verdict: denyVerdict(reason),
+        wwwAuthenticate: challenge(error),
+    });
+    return async (req) => {
+        try {
+            let raw;
+            try {
+                raw = (opts.extract ?? defaultExtract)(req);
+            }
+            catch (e) {
+                return unauth(`unreadable PCActn: ${e.message}`);
+            }
+            if (raw === null || raw === undefined)
+                return unauth('no PCActn presented', 'missing_pcactn');
+            let p;
+            try {
+                p = typeof raw === 'string' ? (0, pca_1.decodePCActn)(raw) : raw;
+            }
+            catch (e) {
+                return unauth(`undecodable PCActn: ${e.message}`, 'invalid_pcactn');
+            }
+            if (p === null || typeof p !== 'object' || typeof p.grant_ref !== 'string') {
+                return unauth('malformed PCActn', 'invalid_pcactn');
+            }
+            const grant = await opts.resolveGrant(p.grant_ref, p);
+            if (!grant)
+                return unauth('unknown grant_ref', 'unknown_grant');
+            const now = opts.now?.() ?? Date.now();
+            const leafHolder = p.cap_chain?.[p.cap_chain.length - 1]?.holder;
+            const key = `${grant.id}:${leafHolder ?? ''}`;
+            const state = opts.budgetStore && leafHolder ? await opts.budgetStore.get(key) : undefined;
+            const ctx = { ...(await opts.context?.(req, p)) };
+            if (state?.budget && ctx.budget === undefined)
+                ctx.budget = state.budget;
+            const verdict = await (0, verify_1.verifyPCActn)(p, { grant, hooks: opts.hooks, now, context: ctx });
+            // Anti-replay (Appendix A step 5): strictly increasing per holder.
+            if (opts.budgetStore) {
+                if (state?.lastCounter !== undefined && !(p.counter > state.lastCounter)) {
+                    verdict.allow = false;
+                    verdict.checks.counter = 'fail';
+                    verdict.reasons.push(`counter: ${String(p.counter)} is not greater than last seen ${state.lastCounter} (replay)`);
+                }
+                else if (verdict.checks.counter === 'pass') {
+                    verdict.checks.counter = 'pass';
+                }
+            }
+            else if (verdict.checks.counter === 'pass') {
+                verdict.checks.counter = 'not-enforced';
+            }
+            if (!verdict.allow) {
+                // A bad signature / chain is an authentication failure; policy denial is authorization.
+                const authnFailed = ['version', 'cap_chain', 'leaf_signature', 'malformed', 'grant_ref'].some((c) => verdict.checks[c] === 'fail');
+                return authnFailed
+                    ? { ok: false, status: 401, verdict, wwwAuthenticate: challenge('invalid_pcactn') }
+                    : { ok: false, status: 403, verdict };
+            }
+            if (opts.budgetStore && leafHolder) {
+                await opts.budgetStore.put(key, { budget: verdict.budget ?? state?.budget, lastCounter: p.counter });
+            }
+            return { ok: true, verdict, pcactn: p };
+        }
+        catch (e) {
+            return { ok: false, status: 403, verdict: denyVerdict(`guard error (fail closed): ${e instanceof Error ? e.message : 'unknown'}`) };
+        }
+    };
+}
+//# sourceMappingURL=require-pca.js.map

package/dist/pca/require-pca.js.map

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

package/dist/pca/verify.d.ts

@@ -0,0 +1,36 @@
+import { type Capability, type CheckStatus, type PCActn, type PlanNode, type RequiredThreshold, type RiskInputs, type TrustBudget, type VerifyHooks } from '@atlasauth/pca';
+/**
+ * Resource-server side Proof-Carrying Authority verifier (spec §4, §7, Appendix A).
+ * Deterministic and offline; never throws (any internal error becomes a fail-closed verdict).
+ */
+export interface PcaContext {
+    /** Plaintext action params. If given they MUST hash to `action.params_digest`; needed by predicates. */
+    params?: Record<string, unknown>;
+    subject?: Record<string, unknown>;
+    env?: Record<string, unknown>;
+    /** The committed plan, if the RS knows it. Its Merkle root must equal `plan.root`. */
+    plan?: PlanNode[];
+    /** Risk inputs the RS can vouch for. Missing ones fail closed (worst case) except `taint`, see below. */
+    risk?: Partial<RiskInputs>;
+    /** Current trust budget for the leaf holder. Absent = a full budget (`budget` check reports not-enforced). */
+    budget?: TrustBudget;
+    recentActionTimes?: number[];
+}
+export interface VerifyPCActnOptions {
+    grant: Capability;
+    hooks?: VerifyHooks;
+    /** epoch ms (default Date.now()) */
+    now?: number;
+    context?: PcaContext;
+}
+export interface PcaVerdict {
+    allow: boolean;
+    /** Recomputed risk score in [0,1]. */
+    r: number;
+    requiredThreshold: RequiredThreshold;
+    checks: Record<string, CheckStatus>;
+    reasons: string[];
+    /** Budget after the decision (leaked, and debited when auto-admitted). Persist it on allow. */
+    budget?: TrustBudget;
+}
+export declare function verifyPCActn(pcactn: PCActn | string, opts: VerifyPCActnOptions): Promise<PcaVerdict>;