@andco/sdk 0.0.2 → 0.0.4

package/dist/oauth.d.ts

@@ -2,28 +2,51 @@ import * as oidc from "openid-client";
 import type { AndcoConfig, AndcoScope } from "./config.js";
 import type { AndcoSession, AndcoUser } from "./credentials.js";
 import { Result } from "./errors.js";
+import type { AndcoGlobals } from "./globals.js";
 /** An RFC 9396 authorization detail. Its shape is owned by the Resource Server that defines it. */
 export type AndcoAuthorizationDetail = {
     readonly type: string;
 } & Readonly<Record<string, unknown>>;
-/** One Resource Server's contribution to a single authorization request. */
+/**
+ * One Resource Server's contribution to a single authorization request.
+ *
+ * Whose resources it asks for lives in each detail's `subject`, for Andco's types and third-party
+ * types alike: absent or `null` is the signed-in Profile, `{ type: "organization" }` lets the person
+ * pick one of their Organizations, and an `identifier` fixes it.
+ *
+ * @example
+ * ```ts
+ * const contribution: AndcoResourceAuthorization = {
+ *   resourceServerId: "00000000-0000-0000-0000-00000000f301",
+ *   resource: "https://openfactura.localhost/api",
+ *   scopes: [],
+ *   authorizationDetails: [
+ *     { type: "documents", actions: ["read"], subject: { type: "organization", identifier: "2" } },
+ *   ],
+ * };
+ * ```
+ */
 export type AndcoResourceAuthorization = {
+    /** Registered Resource Server ID carried by this contribution. */
     readonly resourceServerId: string;
+    /** OAuth Resource Indicator; each distinct contribution becomes a repeated `resource` parameter. */
     readonly resource: string;
     readonly scopes: readonly AndcoScope[];
     readonly authorizationDetails?: readonly AndcoAuthorizationDetail[];
-    readonly orgId?: string;
 };
 /** How an authorization request reaches the Authorization Server. */
 export type AndcoTransportMode = "auto" | "get" | "par";
 /** Everything a caller may vary for one authorization request. */
 export type AndcoAuthorizationOptions = {
+    /** Registered callback URL. Defaults to the instance's `redirectTo`. */
     redirectTo?: string | URL;
+    /** Requested scopes, merged with resource contributions. Defaults to `initialScopes`. */
     scopes?: readonly AndcoScope[];
     /** Immutable contributions from Resource Server Definitions, composed into one request. */
     authorizations?: readonly AndcoResourceAuthorization[];
+    /** Token audiences, merged with resource contributions and deduplicated. */
     resource?: string | readonly string[];
-    orgId?: string;
+    /** Fine-grained permissions merged with resource contributions; selects PAR in `auto` mode. */
     authorizationDetails?: readonly AndcoAuthorizationDetail[];
     /** Opaque destination reference scoped to this OAuth Client. */
     externalId?: string;
@@ -36,10 +59,15 @@ export type AndcoAuthorizationOptions = {
  * terminal's memory.
  */
 export type AndcoAuthorizationRequest = {
+    /** URL to present to the user; may contain a short-lived PAR reference. */
     authorizationUrl: URL;
+    /** Private PKCE verifier; persist with the transaction and never include it in authorization URLs or logs. */
     codeVerifier: string;
+    /** Correlates the callback with this transaction. */
     state: string;
+    /** Exact callback against which the response is validated. */
     redirectTo: string;
+    /** Unix time in milliseconds; callbacks older than ten minutes are rejected. */
     createdAt: number;
 };
 /** RFC 8628 instructions a constrained client displays instead of opening a browser. */
@@ -48,16 +76,21 @@ export type AndcoDeviceAuthorization = {
     userCode: string;
     verificationUri: string;
     verificationUriComplete: string;
+    /** Lifetime of the device code, in seconds. */
     expiresIn: number;
+    /** Minimum polling interval from the server, in seconds. */
     interval: number;
     /** The server response, kept so polling needs no reconstruction by the caller. */
     raw: oidc.DeviceAuthorizationResponse;
 };
+/** OAuth endpoints, client authentication, transport policy, and runtime capabilities. */
 export type AndcoOAuthOptions = {
     config: AndcoConfig;
-    fetch: typeof globalThis.fetch;
+    /** Platform capabilities; only `fetch` is read today. `resolveGlobals()` builds one. */
+    globals: AndcoGlobals;
     /** Present for a confidential client, absent for a public one. */
     clientSecret?: string | null;
+    /** Defaults to `auto`: PAR for sensitive parameters or URLs over 2048 characters, otherwise GET. */
     transport?: AndcoTransportMode;
 };
 /**
@@ -117,8 +150,24 @@ export declare class AndcoOAuth {
     refresh(refreshToken: string): Promise<Result<AndcoSession>>;
     /** Reads the authenticated subject for one access token. */
     userInfo(accessToken: string): Promise<Result<AndcoUser>>;
-    /** Starts RFC 8628 Device Authorization for a runtime that cannot present a browser. */
-    createDeviceAuthorizationRequest(options?: Pick<AndcoAuthorizationOptions, "scopes" | "authorizations">): Promise<Result<AndcoDeviceAuthorization>>;
+    /**
+     * Starts RFC 8628 Device Authorization for a runtime that cannot present a browser.
+     *
+     * Takes the same permissions as {@link createAuthorizationRequest}: scopes, Resource Server
+     * contributions (bound to their server through the same plan, with one `resource` parameter
+     * each) and loose `authorizationDetails`. They travel in the device request's form body, which
+     * the Authorization Server records exactly as it records a pushed request.
+     *
+     * @example
+     * ```ts
+     * const { data: device } = await andco.oauth.createDeviceAuthorizationRequest({
+     *   scopes: ["openid", "email"],
+     *   authorizations: [bank.accounts.authorization({ actions: ["read"], subject: { type: "profile" } })],
+     * });
+     * console.log(device.verificationUriComplete, device.userCode);
+     * ```
+     */
+    createDeviceAuthorizationRequest(options?: Pick<AndcoAuthorizationOptions, "scopes" | "authorizations" | "authorizationDetails" | "resource">): Promise<Result<AndcoDeviceAuthorization>>;
     /**
      * Waits for the user to approve a device authorization, then returns the session.
      *

package/dist/oauth.d.ts.map

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

package/dist/oauth.js

@@ -1,3 +1,4 @@
+import { createAndCoAuthorizationPlan, decodeJwtPayload } from "@andco/protocol";
 import * as oidc from "openid-client";
 import { ANDCO_ERROR_CODES, AndcoError, Result } from "./errors.js";
 import { andcoServerMetadata } from "./server-metadata.generated.js";
@@ -27,13 +28,13 @@ const SENSITIVE_PARAMETERS = ["authorization_details", "login_hint"];
  */
 export class AndcoOAuth {
     #config;
-    #fetch;
+    #globals;
     #clientSecret;
     #transport;
     #configuration;
     constructor(options) {
         this.#config = options.config;
-        this.#fetch = options.fetch;
+        this.#globals = options.globals;
         this.#clientSecret = options.clientSecret ?? null;
         this.#transport = options.transport ?? "auto";
     }
@@ -56,7 +57,7 @@ export class AndcoOAuth {
             return Result.ok({ authorizationUrl, codeVerifier, state, redirectTo, createdAt: Date.now() });
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "authorization_request_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.AUTHORIZATION_REQUEST_FAILED));
         }
     }
     /**
@@ -79,9 +80,12 @@ export class AndcoOAuth {
             }
             const oauthError = callbackUrl.searchParams.get("error");
             if (oauthError) {
-                return Result.fail(oauthError.slice(0, 256), {
+                // The Authorization Server's own RFC 6749 `error` parameter — a foreign vocabulary, not one
+                // of the SDK's own codes, so it is built through the open `AndcoError` constructor rather
+                // than `Result.fail`'s closed shorthand.
+                return Result.fail(new AndcoError(oauthError.slice(0, 256), {
                     message: callbackUrl.searchParams.get("error_description")?.slice(0, 2_048) ?? oauthError,
-                });
+                }));
             }
             else if (!callbackUrl.searchParams.has("code")) {
                 return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK, {
@@ -95,7 +99,7 @@ export class AndcoOAuth {
             return await this.#sessionFrom(tokens);
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "authorization_exchange_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.AUTHORIZATION_EXCHANGE_FAILED));
         }
     }
     /**
@@ -118,7 +122,7 @@ export class AndcoOAuth {
             return Result.ok(await this.#resolveAuthorizationUrl(parameters, transport));
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "authorization_request_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.AUTHORIZATION_REQUEST_FAILED));
         }
     }
     /** Exchanges a refresh token. The caller decides where the rotated token is written. */
@@ -128,7 +132,7 @@ export class AndcoOAuth {
             return await this.#sessionFrom(tokens);
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "refresh_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.REFRESH_FAILED));
         }
     }
     /** Reads the authenticated subject for one access token. */
@@ -137,25 +141,48 @@ export class AndcoOAuth {
             // The subject check compares the UserInfo response against the token's own `sub`, which
             // exists only when the token is a JWT. An opaque token offers nothing to compare, so the
             // check is skipped rather than failing a request that is otherwise valid.
-            const subject = decodeSubject(accessToken);
-            const info = await oidc.fetchUserInfo(this.#oidc(), accessToken, subject ? subject.sub : oidc.skipSubjectCheck);
+            const subject = decodeJwtPayload(accessToken)?.["sub"];
+            const info = await oidc.fetchUserInfo(this.#oidc(), accessToken, typeof subject === "string" ? subject : oidc.skipSubjectCheck);
             return Result.ok({
                 id: String(info.sub),
-                name: info.name,
-                email: info.email,
-                avatarUrl: info.picture,
+                name: typeof info.name === "string" ? info.name : null,
+                email: typeof info.email === "string" ? info.email : null,
+                avatarUrl: typeof info.picture === "string" ? info.picture : null,
+                emailVerified: typeof info.email_verified === "boolean" ? info.email_verified : null,
+                phone: typeof info["phone"] === "string" ? info["phone"] : null,
+                phoneVerified: typeof info["phone_verified"] === "boolean" ? info["phone_verified"] : null,
             });
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "userinfo_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.USERINFO_FAILED));
         }
     }
-    /** Starts RFC 8628 Device Authorization for a runtime that cannot present a browser. */
+    /**
+     * Starts RFC 8628 Device Authorization for a runtime that cannot present a browser.
+     *
+     * Takes the same permissions as {@link createAuthorizationRequest}: scopes, Resource Server
+     * contributions (bound to their server through the same plan, with one `resource` parameter
+     * each) and loose `authorizationDetails`. They travel in the device request's form body, which
+     * the Authorization Server records exactly as it records a pushed request.
+     *
+     * @example
+     * ```ts
+     * const { data: device } = await andco.oauth.createDeviceAuthorizationRequest({
+     *   scopes: ["openid", "email"],
+     *   authorizations: [bank.accounts.authorization({ actions: ["read"], subject: { type: "profile" } })],
+     * });
+     * console.log(device.verificationUriComplete, device.userCode);
+     * ```
+     */
     async createDeviceAuthorizationRequest(options = {}) {
         try {
-            const response = await oidc.initiateDeviceAuthorization(this.#oidc(), {
-                scope: this.#scopes(options).join(" "),
-            });
+            const parameters = new URLSearchParams();
+            const scopes = this.#scopes(options);
+            if (scopes.length)
+                parameters.set("scope", scopes.join(" "));
+            this.#appendPermissions(parameters, options);
+            console.debug("[AndcoOAuth.createDeviceAuthorizationRequest] scopes %s resources %o details %s", scopes.join(" "), parameters.getAll("resource"), parameters.has("authorization_details"));
+            const response = await oidc.initiateDeviceAuthorization(this.#oidc(), parameters);
             return Result.ok({
                 deviceCode: response.device_code,
                 userCode: response.user_code,
@@ -167,7 +194,7 @@ export class AndcoOAuth {
             });
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "device_authorization_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.DEVICE_AUTHORIZATION_FAILED));
         }
     }
     /**
@@ -185,7 +212,7 @@ export class AndcoOAuth {
             return await this.#sessionFrom(tokens);
         }
         catch (cause) {
-            return Result.fail(AndcoError.from(cause, "device_exchange_failed"));
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.DEVICE_EXCHANGE_FAILED));
         }
     }
     /**
@@ -226,7 +253,7 @@ export class AndcoOAuth {
         const configuration = new oidc.Configuration(andcoServerMetadata(issuer), config.clientId, secret ?? undefined, secret ? oidc.ClientSecretBasic(secret) : oidc.None());
         // `CustomFetch` widens the body to include `Uint8Array`, which every runtime's `fetch` accepts
         // as a `BufferSource` even though the standard lib types do not spell it that way.
-        configuration[oidc.customFetch] = ((input, init) => this.#fetch(input, init));
+        configuration[oidc.customFetch] = ((input, init) => this.#globals.fetch(input, init));
         // The Andco Authorization Server is reachable over loopback HTTP in local development.
         oidc.allowInsecureRequests(configuration);
         return configuration;
@@ -245,6 +272,30 @@ export class AndcoOAuth {
         const requested = options.scopes ?? this.#config.initialScopes;
         return [...new Set([...requested, ...contributed])];
     }
+    /**
+     * Appends the `resource` parameters and `authorization_details` both the browser and the device
+     * request carry. Each Resource Server contribution goes through the protocol's plan, which binds
+     * its details to that server (`locations: [resource]`) and refuses details naming different
+     * subjects, loose `authorizationDetails` included. A detail sent without `locations` does not match the server's registered schema and
+     * Andco cannot record it.
+     */
+    #appendPermissions(parameters, options) {
+        const resources = new Set();
+        for (const value of toArray(options.resource))
+            resources.add(value);
+        for (const contribution of options.authorizations ?? [])
+            resources.add(contribution.resource);
+        for (const resource of resources)
+            parameters.append("resource", resource);
+        // Loose details join the plan as a contribution without a resource: they keep their own
+        // `locations`, and their subjects are compared with every contribution's.
+        const plan = createAndCoAuthorizationPlan([
+            { authorizationDetails: options.authorizationDetails ?? [] },
+            ...(options.authorizations ?? []),
+        ]);
+        if (plan.authorizationDetails.length)
+            parameters.set("authorization_details", JSON.stringify(plan.authorizationDetails));
+    }
     #authorizationParameters(options, redirectTo, state, codeChallenge) {
         const parameters = new URLSearchParams({
             client_id: this.#config.clientId,
@@ -257,22 +308,7 @@ export class AndcoOAuth {
         const scopes = this.#scopes(options);
         if (scopes.length)
             parameters.set("scope", scopes.join(" "));
-        const resources = new Set();
-        for (const value of toArray(options.resource))
-            resources.add(value);
-        for (const contribution of options.authorizations ?? [])
-            resources.add(contribution.resource);
-        for (const resource of resources)
-            parameters.append("resource", resource);
-        const details = [
-            ...(options.authorizationDetails ?? []),
-            ...(options.authorizations ?? []).flatMap((a) => [...(a.authorizationDetails ?? [])]),
-        ];
-        if (details.length)
-            parameters.set("authorization_details", JSON.stringify(details));
-        const orgId = options.orgId ?? (options.authorizations ?? []).find((a) => a.orgId)?.orgId;
-        if (orgId)
-            parameters.set("org_id", orgId);
+        this.#appendPermissions(parameters, options);
         if (options.externalId)
             parameters.set("external_id", options.externalId);
         return parameters;
@@ -299,21 +335,30 @@ export class AndcoOAuth {
     }
     async #sessionFrom(tokens) {
         if (tokens.token_type && tokens.token_type.toLowerCase() !== "bearer") {
-            return Result.fail(ANDCO_ERROR_CODES.INVALID_RESPONSE, { message: "unsupported token type" });
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_TOKEN_RESPONSE, { message: "unsupported token type" });
         }
         // The ID Token is where OpenID Connect puts the subject. Reading it out of the access token
         // works only while that token happens to be a JWT, which no specification promises and an
         // Authorization Server may stop doing without warning.
-        const subject = tokens.claims?.()?.sub ?? decodeSubject(tokens.access_token)?.sub;
+        const accessSubject = decodeJwtPayload(tokens.access_token)?.["sub"];
+        const subject = tokens.claims?.()?.sub ?? (typeof accessSubject === "string" ? accessSubject : undefined);
         if (!subject)
-            return Result.fail(ANDCO_ERROR_CODES.INVALID_RESPONSE, { message: "the response carries no subject" });
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_TOKEN_RESPONSE, { message: "the response carries no subject" });
         const session = {
             accessToken: tokens.access_token,
             refreshToken: tokens.refresh_token ?? null,
             tokenType: tokens.token_type ?? "bearer",
             expiresAt: Math.floor(Date.now() / 1000) + (tokens.expires_in ?? 0),
             scopes: (tokens.scope ?? "").split(/\s+/).filter(Boolean),
-            user: { id: subject, name: null, email: null, avatarUrl: null },
+            user: {
+                id: subject,
+                name: null,
+                email: null,
+                avatarUrl: null,
+                emailVerified: null,
+                phone: null,
+                phoneVerified: null,
+            },
         };
         const user = await this.userInfo(session.accessToken);
         return Result.ok(user.data ? { ...session, user: user.data } : session);
@@ -330,19 +375,3 @@ function callbackMatchesRedirect(actual, expected) {
         return false;
     return [...expected.searchParams].every(([key, value]) => actual.searchParams.getAll(key).includes(value));
 }
-/** Reads `sub` from an access token without verifying it; the server remains the authority. */
-function decodeSubject(accessToken) {
-    const segments = accessToken.split(".");
-    if (segments.length < 2 || !segments[1])
-        return null;
-    try {
-        const payload = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(segments[1].replace(/-/g, "+").replace(/_/g, "/")), (character) => character.charCodeAt(0))));
-        if (payload && typeof payload === "object" && typeof payload.sub === "string") {
-            return { sub: payload.sub };
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}

package/dist/presenter.d.ts

@@ -1,9 +1,23 @@
-import type { Result } from "./errors.js";
+import { Result } from "./errors.js";
 /** How an authorization is put in front of the user. */
 export type AndcoPresentation = "popup" | "redirect";
-export type AndcoPresentOptions = {
-    url: URL;
-    presentation: AndcoPresentation;
+/**
+ * How an Intent is put in front of the user. `"newtab"` is a popup without window features: same
+ * relay back to the opener, for where popups are blocked.
+ */
+export type AndcoIntentPresentation = "popup" | "newtab" | "redirect";
+/**
+ * The destination, or a thunk that resolves it.
+ *
+ * A thunk is what lets a presenter open its window *during* the user activation and navigate it
+ * afterwards. Both flows need it: an authorization request may be pushed (PAR) before its URL
+ * exists, and an Intent is created only once someone asked for it. Awaiting either before opening
+ * is what gets the window blocked. A thunk that cannot resolve throws an {@link AndcoError} rather
+ * than returning one; {@link AndcoPresenter.present} is what turns that back into a `Result` for a presenter.
+ */
+export type AndcoPresentTarget = URL | (() => Promise<URL>);
+type AndcoPresentBase = {
+    url: AndcoPresentTarget;
     /** Exact callback the Authorization Server will reach on success. */
     returnTo: URL;
     /** Exact callback reached on failure. Defaults to `returnTo`. */
@@ -12,11 +26,34 @@ export type AndcoPresentOptions = {
     presentationId: string;
     signal?: AbortSignal;
 };
+/** An authorization. Its callback carries a single-use code the opener must exchange. */
+export type AndcoPresentOAuth = AndcoPresentBase & {
+    kind: "oauth";
+    presentation: AndcoPresentation;
+};
+/**
+ * An Intent. Its callback carries a lifecycle outcome only — the authenticated read decides the
+ * financial fact — and `intentId` is what lets a presenter with no window, such as a native Host,
+ * resolve current state from the Resource Server instead.
+ */
+export type AndcoPresentIntent = AndcoPresentBase & {
+    kind: "intent";
+    /** A `"redirect"` that navigates answers `null`; its result is read by `andco.intents.fromCallback`. */
+    presentation: AndcoIntentPresentation;
+    /** Empty until the thunk has resolved; a presenter reads it after resolution, never before. */
+    readonly intentId: string;
+};
+export type AndcoPresentOptions = AndcoPresentOAuth | AndcoPresentIntent;
 /**
  * The boundary between the protocol and whatever shows it to a person.
  *
- * A presenter receives an authorization URL and answers with the callback URL that came back, or
- * `null` when the user dismissed. It owns no protocol: no PKCE, no state, no token exchange.
+ * A presenter receives a destination and answers with the callback URL that came back, or `null`
+ * when the user dismissed. It owns no protocol: no PKCE, no state, no token exchange, and no
+ * opinion about what a completed Intent means.
+ *
+ * `kind` is the seam's only domain knowledge, and it exists because a presenter without a window
+ * cannot treat the two alike: a native Host runs its own consent screen for an authorization and
+ * its own review screen for an Intent. A browser presents both the same way and ignores it.
  *
  * Keeping it this narrow is what makes sign-in testable without a browser — a test supplies a
  * presenter that returns a prepared callback URL and the whole flow runs in plain Node. It is also
@@ -25,12 +62,23 @@ export type AndcoPresentOptions = {
  *
  * @example
  * ```ts
- * const presenter: AndcoPresenter = {
- *   present: async ({ url }) => Result.ok(new URL(`${redirectTo}?code=test&state=${state}`)),
- * };
+ * class Presenter extends AndcoPresenter {
+ *   async present({ returnTo }: AndcoPresentOptions) {
+ *     return Result.ok(new URL(`${returnTo}?code=test&state=${state}`));
+ *   }
+ * }
  * ```
  */
-export interface AndcoPresenter {
-    present(options: AndcoPresentOptions): Promise<Result<URL | null>>;
+export declare abstract class AndcoPresenter {
+    /** Resolves a presentation target, whether it was already a URL or still a thunk. */
+    static present(target: AndcoPresentTarget): Promise<Result<URL>>;
+    abstract present(options: AndcoPresentOptions): Promise<Result<URL | null>>;
+    /**
+     * Brings the window of a presentation that is still open to the front, so presenting the same
+     * Intent twice shows the one window instead of opening a second. A presenter with no window of
+     * its own, such as a native Host that owns its screen, simply omits it.
+     */
+    focus?(presentationId: string): void;
 }
+export {};
 //# sourceMappingURL=presenter.d.ts.map

package/dist/presenter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presenter.d.ts","sourceRoot":"","sources":["../src/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,UAAU,CAAC;AAErD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,iBAAiB,CAAC;IAChC,qEAAqE;IACrE,QAAQ,EAAE,GAAG,CAAC;IACd,iEAAiE;IACjE,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC;CACpE"}
+{"version":3,"file":"presenter.d.ts","sourceRoot":"","sources":["../src/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,MAAM,EAAE,MAAM,aAAa,CAAC;AAEpE,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,UAAU,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,GAAG,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AAE5D,KAAK,gBAAgB,GAAG;IACtB,GAAG,EAAE,kBAAkB,CAAC;IACxB,qEAAqE;IACrE,QAAQ,EAAE,GAAG,CAAC;IACd,iEAAiE;IACjE,aAAa,CAAC,EAAE,GAAG,CAAC;IACpB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG;IACjD,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,iBAAiB,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG;IAClD,IAAI,EAAE,QAAQ,CAAC;IACf,wGAAwG;IACxG,YAAY,EAAE,uBAAuB,CAAC;IACtC,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,cAAc;IAClC,qFAAqF;WACxE,OAAO,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAWtE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAE3E;;;;OAIG;IACH,KAAK,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;CACrC"}

package/dist/presenter.js

@@ -1 +1,40 @@
-export {};
+import { ANDCO_ERROR_CODES, AndcoError, Result } from "./errors.js";
+/**
+ * The boundary between the protocol and whatever shows it to a person.
+ *
+ * A presenter receives a destination and answers with the callback URL that came back, or `null`
+ * when the user dismissed. It owns no protocol: no PKCE, no state, no token exchange, and no
+ * opinion about what a completed Intent means.
+ *
+ * `kind` is the seam's only domain knowledge, and it exists because a presenter without a window
+ * cannot treat the two alike: a native Host runs its own consent screen for an authorization and
+ * its own review screen for an Intent. A browser presents both the same way and ignores it.
+ *
+ * Keeping it this narrow is what makes sign-in testable without a browser — a test supplies a
+ * presenter that returns a prepared callback URL and the whole flow runs in plain Node. It is also
+ * why a redirect presentation can answer with `null` and never resolve: the document is replaced,
+ * and the result arrives on the next page load instead.
+ *
+ * @example
+ * ```ts
+ * class Presenter extends AndcoPresenter {
+ *   async present({ returnTo }: AndcoPresentOptions) {
+ *     return Result.ok(new URL(`${returnTo}?code=test&state=${state}`));
+ *   }
+ * }
+ * ```
+ */
+export class AndcoPresenter {
+    /** Resolves a presentation target, whether it was already a URL or still a thunk. */
+    static async present(target) {
+        if (target instanceof URL) {
+            return Result.ok(target);
+        }
+        try {
+            return Result.ok(await target());
+        }
+        catch (cause) {
+            return Result.fail(AndcoError.from(cause, ANDCO_ERROR_CODES.PRESENTATION_TARGET_FAILED));
+        }
+    }
+}

package/dist/resource.d.ts

@@ -0,0 +1,109 @@
+import { Result } from "./errors.js";
+import type { AndcoGrantAuthorization, AndcoGrants } from "./grants-api.js";
+import type { AndcoTokens } from "./tokens.js";
+/** One RAR detail a route needs the Grant to carry: the type, and every action it uses. */
+export type AndcoDetailRequirement = {
+    readonly type: string;
+    readonly actions?: readonly string[];
+};
+/** What a protected route requires of the caller's Grant. Everything omitted is not checked. */
+export type AndcoProtectOptions = {
+    /** Scopes the Grant must carry, all of them. */
+    scopes?: readonly string[];
+    /** RAR details the Grant must carry; each needs a detail of that type including its actions. */
+    authorizationDetails?: readonly AndcoDetailRequirement[];
+    /**
+     * Verify the token offline first (signature, `exp`, `iss`, and `aud` equal to the resource), so a
+     * forged token never costs a request to Andco. Off by default: it assumes the Authorization Server
+     * addresses tokens to this resource.
+     */
+    verify?: boolean;
+};
+/** A guard answered `Response` to reject the request, or the live Grant to let it through. */
+export type AndcoProtectOutcome = Result<AndcoGrantAuthorization> | Response;
+/** Hono's `Context`, as far as the adapter needs it. */
+type HonoLikeContext = {
+    req: {
+        raw: Request;
+    };
+    set(key: "andcoGrant", value: AndcoGrantAuthorization): void;
+};
+/** Express's request, as far as the adapter needs it. */
+type ExpressLikeRequest = {
+    headers: Record<string, string | string[] | undefined>;
+};
+/** Express's response, as far as the adapter needs it. */
+type ExpressLikeResponse = {
+    locals: Record<string, unknown>;
+    status(code: number): unknown;
+    setHeader(name: string, value: string): unknown;
+    send(body: string): unknown;
+};
+/**
+ * A route guard built by {@link AndcoResource.protect}. Call it with a Fetch `Request`, or plug one
+ * of its adapters into a framework.
+ */
+export type AndcoProtection = {
+    (request: Request): Promise<AndcoProtectOutcome>;
+    /** Hono middleware. The Grant is available as `c.get("andcoGrant")`. */
+    hono(): (context: HonoLikeContext, next: () => Promise<void>) => Promise<Response | undefined>;
+    /** Express middleware. The Grant is available as `res.locals.andcoGrant`. */
+    express(): (request: ExpressLikeRequest, response: ExpressLikeResponse, next: () => void) => Promise<void>;
+};
+/**
+ * One Resource Server's view of Andco: verify the bearer token, fetch the live Grant, and answer
+ * 401 or 403 the way RFC 6750 and RFC 9728 describe.
+ *
+ * @example
+ * ```ts
+ * const orders = andco.resource({ resource: "https://casa-norte.example/api" });
+ *
+ * // Fetch-style handler (Next route handlers, Workers, Bun, Deno)
+ * export async function GET(request: Request) {
+ *   const outcome = await orders.protect({ scopes: ["orders:read"] })(request);
+ *   if (outcome instanceof Response) return outcome; // 401 or 403, already built
+ *   return Response.json(await listOrders(outcome.data.subject));
+ * }
+ *
+ * // Hono
+ * app.use("/api/orders/*", orders.protect({ authorizationDetails: [{ type: "orders", actions: ["read"] }] }).hono());
+ *
+ * // Express
+ * router.get("/api/orders", orders.protect({ scopes: ["orders:read"] }).express(), handler);
+ * ```
+ */
+export declare class AndcoResource {
+    #private;
+    readonly resource: string;
+    /** Where `WWW-Authenticate` points clients for this resource's metadata (RFC 9728). */
+    readonly resourceMetadata: string;
+    constructor(options: {
+        resource: string;
+        /** Overrides the RFC 9728 well-known URL derived from `resource`. */
+        resourceMetadata?: string;
+        tokens: AndcoTokens;
+        grants: AndcoGrants;
+    });
+    /**
+     * The document to publish at {@link resourceMetadata}, so clients can discover the Authorization Server.
+     *
+     * @example
+     * ```ts
+     * app.get("/.well-known/oauth-protected-resource/api", (_req, res) =>
+     *   res.json(orders.metadata({ scopesSupported: ["orders:read"] })),
+     * );
+     * ```
+     */
+    metadata(options?: {
+        scopesSupported?: readonly string[];
+    }): {
+        resource: string;
+        authorization_servers: string[];
+        bearer_methods_supported: string[];
+        scopes_supported: readonly string[] | undefined;
+    };
+    /** Builds a guard requiring a live Grant for this resource that satisfies `options`. */
+    protect(options?: AndcoProtectOptions): AndcoProtection;
+}
+export {};
+//# sourceMappingURL=resource.d.ts.map