@andco/sdk 0.0.3 → 0.0.4

package/dist/cli/server.js

@@ -1,4 +1,5 @@
 import { createServer } from "node:http";
+/** Local OAuth callback receiver. The caller owns state/PKCE validation and server cleanup. */
 export class LoopbackServer {
     #server;
     #resolveCallback;
@@ -7,6 +8,7 @@ export class LoopbackServer {
         this.#redirectUri = configured;
         this.#server = this.#buildServer();
     }
+    /** Starts listening; a missing port selects an available port reflected in `redirectUri`. */
     static async start(configured) {
         const receiver = new LoopbackServer(configured);
         await receiver.listen();
@@ -19,9 +21,11 @@ export class LoopbackServer {
         receiver.#redirectUri.port = String(address.port);
         return receiver;
     }
+    /** Exact callback URL including the port allocated by the operating system. */
     get redirectUri() {
         return this.#redirectUri;
     }
+    /** Waits for a callback or returns `null` on timeout. Call `close()` after either outcome. */
     wait(timeoutMs) {
         return new Promise((resolve) => {
             this.#resolveCallback = resolve;
@@ -30,6 +34,7 @@ export class LoopbackServer {
             timer.unref?.();
         });
     }
+    /** Closes the listener and any remaining connections. */
     close() {
         return new Promise((resolve) => {
             this.#server.closeAllConnections?.();

package/dist/client.d.ts

@@ -1,16 +1,22 @@
-import type { AndCoRandomSource } from "@andco/protocol";
 import { AndcoAuth } from "./auth.js";
 import { type AndcoConfig, type AndcoConfigInput } from "./config.js";
 import { type AndcoCredentials, type AndcoSession } from "./credentials.js";
+import { type AndcoGlobals } from "./globals.js";
+import { AndcoGrants } from "./grants-api.js";
+import type { AndcoInflight } from "./inflight.js";
 import { AndcoIntents } from "./intents.js";
 import { type AndcoAuthorizationRequest, AndcoOAuth, type AndcoTransportMode } from "./oauth.js";
-import type { AndcoPresenter } from "./presenter.js";
+import { AndcoPresenter } from "./presenter.js";
+import { AndcoResource } from "./resource.js";
 import { AndcoRest } from "./rest.js";
 import { type AndcoSessionSource, AndcoSessionStore } from "./session-store.js";
-import type { AndcoLock, AndcoStorage } from "./storage.js";
+import type { AndcoStorage } from "./storage.js";
+import { AndcoTokens } from "./tokens.js";
 /** A Resource Server Definition: immutable, and able to bind itself to a client. */
 export interface AndcoResourceServer<Client> {
+    /** Registered Resource Server ID used in authorization contributions. */
     readonly id: string;
+    /** OAuth Resource Indicator used to select the matching bearer credential. */
     readonly resource: string;
     /**
      * Produces an operational client for this Resource Server from resolved credentials.
@@ -21,15 +27,11 @@ export interface AndcoResourceServer<Client> {
      */
     use(credentials: AndcoCredentials): Client;
 }
-/** Platform capabilities the SDK reads off the runtime, grouped so a future addition is not a breaking change. */
-export type AndcoGlobals = {
-    fetch: typeof globalThis.fetch;
-    /** Threaded into the Protocol Contract's `RANDOM_UUID`, so a runtime without Web Crypto can supply its own. */
-    crypto: AndCoRandomSource;
-};
+/** Configuration and runtime capabilities shared by browser, server, and CLI instances. */
 export type AndcoClientOptions = AndcoConfigInput & {
     /** Confidential credential. Its presence is what makes this a confidential OAuth client. */
     clientSecret?: string | null;
+    /** Overrides runtime fetch and randomness; omitted capabilities use platform defaults. */
     globals?: Partial<AndcoGlobals>;
     /** Authorization Transport Policy. Defaults to `auto`. */
     transport?: AndcoTransportMode;
@@ -37,14 +39,66 @@ export type AndcoClientOptions = AndcoConfigInput & {
     presenter?: AndcoPresenter;
     /** Persists a transaction so it survives a full-page redirect. */
     persistTransaction?: (request: AndcoAuthorizationRequest) => void | Promise<void>;
+    /** Session persistence adapter. Defaults to memory unless a runtime factory supplies one. */
     storage?: AndcoStorage;
     /** A session the caller already resolved, so the first snapshot is real rather than unresolved. */
     initialSession?: AndcoSession | null;
-    lock?: AndcoLock;
+    /** Shares one refresh among concurrent callers. Defaults to sharing within this runtime. */
+    inflight?: AndcoInflight;
     /** Consulted once during the load, before storage. This is where a URL callback enters. */
     source?: AndcoSessionSource;
+    /** Writes session changes to storage unless `false`; defaults to `true`. */
     persist?: boolean;
 };
+/**
+ * The eight collaborator fields shared, verbatim, by {@link AndcoClient} and both of the authorized
+ * views behind `with(...)` and `authorized()`. Declaring them once here is what keeps adding a field
+ * to the instance from requiring three synchronized edits.
+ *
+ * This is a construction seam, not a claim that the three are interchangeable: each subclass still
+ * decides for itself — per the ADR-0023 invariants documented at `AndcoAuthedClientImpl` and
+ * `AndcoAuthorizedViewImpl` — whether a given field's value is freshly built or borrowed by reference
+ * from an owner. The base constructor only stores whatever it is handed.
+ */
+declare class AndcoClientFields {
+    readonly config: AndcoConfig;
+    readonly clientSecret: string | null;
+    readonly globals: AndcoGlobals;
+    readonly oauth: AndcoOAuth;
+    readonly rest: AndcoRest;
+    readonly intents: AndcoIntents;
+    readonly auth: AndcoAuth;
+    readonly session: AndcoSessionStore;
+    /** Offline verification of access tokens with the Authorization Server JWKS. */
+    readonly tokens: AndcoTokens;
+    /** Live Grant lookup for a token. */
+    readonly grants: AndcoGrants;
+    protected constructor(fields: {
+        config: AndcoConfig;
+        clientSecret: string | null;
+        globals: AndcoGlobals;
+        oauth: AndcoOAuth;
+        rest: AndcoRest;
+        intents: AndcoIntents;
+        auth: AndcoAuth;
+        session: AndcoSessionStore;
+        tokens: AndcoTokens;
+        grants: AndcoGrants;
+    });
+    /**
+     * Acts as the Resource Server identified by `resource`: verifies tokens and protects routes.
+     *
+     * @example
+     * ```ts
+     * const orders = andco.resource({ resource: "https://casa-norte.example/api" });
+     * app.use("/api/orders/*", orders.protect({ scopes: ["orders:read"] }).hono());
+     * ```
+     */
+    resource(options: {
+        resource: string;
+        resourceMetadata?: string;
+    }): AndcoResource;
+}
 /**
  * An Andco Instance without resolved credentials.
  *
@@ -65,15 +119,7 @@ export type AndcoClientOptions = AndcoConfigInput & {
  * const bound = andco.with(await sessionFromCookie());
  * ```
  */
-export declare class AndcoClient {
-    readonly config: AndcoConfig;
-    readonly clientSecret: string | null;
-    readonly globals: AndcoGlobals;
-    readonly oauth: AndcoOAuth;
-    readonly rest: AndcoRest;
-    readonly intents: AndcoIntents;
-    readonly auth: AndcoAuth;
-    readonly session: AndcoSessionStore;
+export declare class AndcoClient extends AndcoClientFields {
     /** Runtime discriminant: `false` here, `true` on the value `with(...)` returns. */
     readonly isAuthed: false;
     constructor(options: AndcoClientOptions);
@@ -132,4 +178,5 @@ export declare class AndcoClient {
 export type AndcoClientAuthed = Omit<AndcoClient, "isAuthed" | "with" | "authorized"> & AndcoCredentials & {
     readonly isAuthed: true;
 };
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -2,10 +2,63 @@ import { AndcoAuth } from "./auth.js";
 import { AndcoConfig as Config } from "./config.js";
 import { credentialsFromSession, isCredentials } from "./credentials.js";
 import { Result } from "./errors.js";
+import { resolveGlobals } from "./globals.js";
+import { AndcoGrants } from "./grants-api.js";
 import { AndcoIntents } from "./intents.js";
 import { AndcoOAuth } from "./oauth.js";
+import { AndcoPresenter } from "./presenter.js";
+import { AndcoResource } from "./resource.js";
 import { AndcoRest } from "./rest.js";
 import { AndcoSessionStore, browserRequired } from "./session-store.js";
+import { AndcoTokens } from "./tokens.js";
+/**
+ * The eight collaborator fields shared, verbatim, by {@link AndcoClient} and both of the authorized
+ * views behind `with(...)` and `authorized()`. Declaring them once here is what keeps adding a field
+ * to the instance from requiring three synchronized edits.
+ *
+ * This is a construction seam, not a claim that the three are interchangeable: each subclass still
+ * decides for itself — per the ADR-0023 invariants documented at `AndcoAuthedClientImpl` and
+ * `AndcoAuthorizedViewImpl` — whether a given field's value is freshly built or borrowed by reference
+ * from an owner. The base constructor only stores whatever it is handed.
+ */
+class AndcoClientFields {
+    config;
+    clientSecret;
+    globals;
+    oauth;
+    rest;
+    intents;
+    auth;
+    session;
+    /** Offline verification of access tokens with the Authorization Server JWKS. */
+    tokens;
+    /** Live Grant lookup for a token. */
+    grants;
+    constructor(fields) {
+        this.config = fields.config;
+        this.clientSecret = fields.clientSecret;
+        this.globals = fields.globals;
+        this.oauth = fields.oauth;
+        this.rest = fields.rest;
+        this.intents = fields.intents;
+        this.auth = fields.auth;
+        this.session = fields.session;
+        this.tokens = fields.tokens;
+        this.grants = fields.grants;
+    }
+    /**
+     * Acts as the Resource Server identified by `resource`: verifies tokens and protects routes.
+     *
+     * @example
+     * ```ts
+     * const orders = andco.resource({ resource: "https://casa-norte.example/api" });
+     * app.use("/api/orders/*", orders.protect({ scopes: ["orders:read"] }).hono());
+     * ```
+     */
+    resource(options) {
+        return new AndcoResource({ ...options, tokens: this.tokens, grants: this.grants });
+    }
+}
 /**
  * An Andco Instance without resolved credentials.
  *
@@ -26,60 +79,52 @@ import { AndcoSessionStore, browserRequired } from "./session-store.js";
  * const bound = andco.with(await sessionFromCookie());
  * ```
  */
-export class AndcoClient {
-    config;
-    clientSecret;
-    globals;
-    oauth;
-    rest;
-    intents;
-    auth;
-    session;
+export class AndcoClient extends AndcoClientFields {
     /** Runtime discriminant: `false` here, `true` on the value `with(...)` returns. */
     isAuthed = false;
     constructor(options) {
-        this.config = Config.from(options);
-        this.clientSecret = options.clientSecret ?? null;
-        this.globals = {
-            fetch: options.globals?.fetch ?? globalThis.fetch.bind(globalThis),
-            crypto: options.globals?.crypto ?? globalThis.crypto,
-        };
-        this.oauth = new AndcoOAuth({
-            config: this.config,
-            fetch: this.globals.fetch,
-            clientSecret: this.clientSecret,
+        const config = Config.from(options);
+        const clientSecret = options.clientSecret ?? null;
+        const globals = resolveGlobals(options.globals);
+        const oauth = new AndcoOAuth({
+            config,
+            globals,
+            clientSecret,
             transport: options.transport,
         });
         // The store is real even without a presenter: it is what lets `rest` stay one object across a
         // sign-in, and what gives `auth` something to operate on regardless of runtime.
-        this.session = new AndcoSessionStore({
-            config: this.config,
-            oauth: this.oauth,
+        const session = new AndcoSessionStore({
+            config,
+            oauth,
             storage: options.storage,
             initialSession: options.initialSession,
-            lock: options.lock,
+            inflight: options.inflight,
             source: options.source,
             persist: options.persist,
         });
         // One presenter for the whole instance: authorization and Intent are the same seam, so a
         // runtime that can present one can present the other. Not public — nothing outside the
         // instance chooses how it presents, and every mirror of this type would have to carry it.
-        const presenter = options.presenter ?? statelessPresenter();
-        this.auth = new AndcoAuth({
-            config: this.config,
-            oauth: this.oauth,
-            store: this.session,
+        const presenter = options.presenter ?? new AndcoPresenterStateless();
+        const auth = new AndcoAuth({
+            config,
+            oauth,
+            store: session,
             presenter,
             persistTransaction: options.persistTransaction,
-            crypto: this.globals.crypto,
+            globals,
         });
-        this.rest = new AndcoRest({ config: this.config, fetch: this.globals.fetch, credentials: this.session });
-        this.intents = new AndcoIntents({
-            rest: this.rest,
-            config: this.config,
+        const rest = new AndcoRest({ config, globals, credentials: session });
+        const intents = new AndcoIntents({
+            rest,
+            config,
             presenter,
-            crypto: this.globals.crypto,
+            globals,
         });
+        const tokens = new AndcoTokens({ config, globals });
+        const grants = new AndcoGrants({ config, globals });
+        super({ config, clientSecret, globals, oauth, rest, intents, auth, session, tokens, grants });
     }
     /**
      * Binds *explicit* credentials for one unit of work, owning its own REST surface.
@@ -141,47 +186,45 @@ export class AndcoClient {
     }
 }
 /** Presents nothing; every authorization attempt fails clearly instead of doing nothing silently. */
-function statelessPresenter() {
-    return {
-        async present() {
-            return Result.fail(browserRequired());
-        },
-    };
+class AndcoPresenterStateless extends AndcoPresenter {
+    async present() {
+        return Result.fail(browserRequired());
+    }
 }
 /**
  * The implementation behind `with(...)`. Not exported: `AndcoClientAuthed` is the entire public
  * contract, so a caller never has a reason to name this type.
  */
-class AndcoAuthedClientImpl {
+class AndcoAuthedClientImpl extends AndcoClientFields {
     credentials;
     isAuthed = true;
-    config;
-    clientSecret;
-    globals;
-    oauth;
-    rest;
-    intents;
-    auth;
-    session;
     constructor(owner, credentials) {
-        this.credentials = credentials;
-        this.config = owner.config;
-        this.clientSecret = owner.clientSecret;
-        this.globals = owner.globals;
-        this.oauth = owner.oauth;
-        this.rest = new AndcoRest({ config: owner.config, fetch: owner.globals.fetch, credentials });
+        const rest = new AndcoRest({ config: owner.config, globals: owner.globals, credentials });
         // No presenter: `with(...)` is the per-request server shape, and a request presents nothing.
-        this.intents = new AndcoIntents({ rest: this.rest, config: owner.config, crypto: owner.globals.crypto });
+        const intents = new AndcoIntents({ rest, config: owner.config, globals: owner.globals });
         // In-memory and unlinked from `credentials`: it exists only so `auth` has something to operate
         // on, since a bare token or a caller-supplied resolver carries no persistable session shape.
-        this.session = new AndcoSessionStore({ config: owner.config, oauth: owner.oauth, persist: false });
-        this.auth = new AndcoAuth({
+        const session = new AndcoSessionStore({ config: owner.config, oauth: owner.oauth, persist: false });
+        const auth = new AndcoAuth({
+            config: owner.config,
+            oauth: owner.oauth,
+            store: session,
+            presenter: new AndcoPresenterStateless(),
+            globals: owner.globals,
+        });
+        super({
             config: owner.config,
+            clientSecret: owner.clientSecret,
+            globals: owner.globals,
             oauth: owner.oauth,
-            store: this.session,
-            presenter: statelessPresenter(),
-            crypto: owner.globals.crypto,
+            rest,
+            intents,
+            auth,
+            session,
+            tokens: owner.tokens,
+            grants: owner.grants,
         });
+        this.credentials = credentials;
     }
     accessTokenFor(resource) {
         return this.credentials.accessTokenFor(resource);
@@ -193,27 +236,23 @@ class AndcoAuthedClientImpl {
  * unchanged across a sign-in, satisfying "one REST surface per instance" even where a framework
  * adapter hands out a fresh `AndcoClientAuthed` reference on every Authorized Identity change.
  */
-class AndcoAuthorizedViewImpl {
+class AndcoAuthorizedViewImpl extends AndcoClientFields {
     owner;
     isAuthed = true;
-    config;
-    clientSecret;
-    globals;
-    oauth;
-    rest;
-    intents;
-    auth;
-    session;
     constructor(owner) {
+        super({
+            config: owner.config,
+            clientSecret: owner.clientSecret,
+            globals: owner.globals,
+            oauth: owner.oauth,
+            rest: owner.rest,
+            intents: owner.intents,
+            auth: owner.auth,
+            session: owner.session,
+            tokens: owner.tokens,
+            grants: owner.grants,
+        });
         this.owner = owner;
-        this.config = owner.config;
-        this.clientSecret = owner.clientSecret;
-        this.globals = owner.globals;
-        this.oauth = owner.oauth;
-        this.rest = owner.rest;
-        this.intents = owner.intents;
-        this.auth = owner.auth;
-        this.session = owner.session;
     }
     /** Delegates to the instance's own session store on every call, so a rotated token is still picked up. */
     accessTokenFor(resource) {

package/dist/config.d.ts

@@ -5,7 +5,7 @@ export type AndcoTheme = "base";
  * An OAuth scope. Known Andco scopes are suggested; a Resource Server may define its own.
  *
  * The Protocol Contract already knows the scope vocabulary, so this is that type rather than a bare
- * `string`: an editor completes `bank_accounts:read` without closing the door on a scope Andco has
+ * `string`: an editor completes `offline_access` without closing the door on a scope Andco has
  * not shipped yet.
  */
 export type AndcoScope = AndCoScope;
@@ -75,6 +75,7 @@ export declare class AndcoConfig {
     widgetURL(release: number, surface?: "button"): URL;
     /** Whether an origin may participate in popup messaging for this instance. */
     allowsPopupOrigin(origin: string): boolean;
+    /** Serializes configuration to constructor input without credentials or runtime collaborators. */
     toJSON(): AndcoConfigInput;
 }
 /** Loopback over plain HTTP is accepted so local development and CLI callbacks work unmodified. */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAChC;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC;AAEpC,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC5B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC9B,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC1B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,GAAG,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAC1E,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,GAAG,GAAG,SAAS,CAAC;IAC5C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,UAAU,CAAC;IAClC,SAAgB,SAAS,EAAE,cAAc,CAAC;IAC1C,SAAgB,aAAa,EAAE,SAAS,UAAU,EAAE,CAAC;IACrD,SAAgB,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzD,OAAO;IAkCP,mGAAmG;WACrF,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW;IAIxD,mDAAmD;IAC5C,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,WAAW;IAI9D;;;OAGG;IACI,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAOjC,oDAAoD;IAC7C,MAAM,IAAI,GAAG;IAIpB,qEAAqE;IAC9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,QAAmB,GAAG,GAAG;IAIpE,8EAA8E;IACvE,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI1C,MAAM,IAAI,gBAAgB;CAelC;AAED,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAQ5C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAGzB,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAChC;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC;AAEpC,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC5B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC9B,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC1B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAMF;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,SAAS,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,GAAG,CAAC;QAAC,GAAG,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAC1E,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,GAAG,GAAG,SAAS,CAAC;IAC5C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,UAAU,CAAC;IAClC,SAAgB,SAAS,EAAE,cAAc,CAAC;IAC1C,SAAgB,aAAa,EAAE,SAAS,UAAU,EAAE,CAAC;IACrD,SAAgB,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzD,OAAO;IAkCP,mGAAmG;WACrF,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW;IAIxD,mDAAmD;IAC5C,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,WAAW;IAI9D;;;OAGG;IACI,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAOjC,oDAAoD;IAC7C,MAAM,IAAI,GAAG;IAIpB,qEAAqE;IAC9D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,QAAmB,GAAG,GAAG;IAIpE,8EAA8E;IACvE,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIjD,kGAAkG;IAC3F,MAAM,IAAI,gBAAgB;CAelC;AAED,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAQ5C"}

package/dist/config.js

@@ -83,6 +83,7 @@ export class AndcoConfig {
     allowsPopupOrigin(origin) {
         return this.allowedPopupOrigins.has(origin);
     }
+    /** Serializes configuration to constructor input without credentials or runtime collaborators. */
     toJSON() {
         return {
             clientId: this.clientId,

package/dist/credentials.d.ts

@@ -1,9 +1,37 @@
+import type { AndcoConfig } from "./config.js";
+import type { GrantReference } from "./grants.js";
 /** The authenticated subject of a session, as far as the SDK is concerned. */
 export type AndcoUser = {
     id: string;
     name: string | null;
     email: string | null;
     avatarUrl: string | null;
+    /**
+     * Whether the Authorization Server has verified the email address.
+     *
+     * `true` and `false` are both affirmative claims the server made; `null` means the server said
+     * nothing about it. Absence must never be treated as verified, which is why this is required
+     * rather than optional: every constructor of an `AndcoUser` must say what it knows, instead of
+     * silently forgetting to say anything.
+     */
+    emailVerified: boolean | null;
+    /**
+     * The Profile's phone number, as UserInfo's `phone` claim carries it. `null` unless the `phone`
+     * scope was granted and the Profile has a number on file.
+     *
+     * @example
+     * ```ts
+     * await andco.auth.signIn({ scopes: ["openid", "phone"] });
+     * andco.session.getSnapshot()?.user.phone; // "+56999999999"
+     * ```
+     */
+    phone: string | null;
+    /**
+     * `true` when the Authorization Server confirmed the phone number; `null` when it said nothing,
+     * which includes a number not yet confirmed and a session without the `phone` scope. Like
+     * `emailVerified`, absence never means verified.
+     */
+    phoneVerified: boolean | null;
 };
 /**
  * One set of credentials issued by Andco.
@@ -23,12 +51,23 @@ export type AndcoSession = {
     /** Access tokens keyed by exact Resource Indicator URI. Absent means `accessToken` serves all. */
     resourceAccessTokens?: Readonly<Record<string, string>>;
 };
+/**
+ * Per-request authorization controls a transport hands to the credentials.
+ *
+ * Only an explicit `grant` exists: the Authorization Server selects the Grant from the client,
+ * the subject and the resource, so the SDK never inspects request paths or bodies to guess it.
+ */
+export type AndcoCredentialRequest = {
+    /** Exact Grant to use for this request instead of the server's selection. */
+    readonly grant?: GrantReference;
+};
 /**
  * The entire contract the Andco core knows about authorization.
  *
- * Keeping it to one resource-keyed method is what lets an application go on owning its sessions:
+ * Keeping one required resource-keyed method lets an application go on owning its sessions:
  * a Better Auth account, a Passport session, a row in your own table, or a plain closure all
- * satisfy it without adopting the SDK's persistence.
+ * satisfy it without adopting the SDK's persistence. Service credentials also receive the explicit
+ * `grant` control and may provide request-local authority through `forOperation()`.
  *
  * @example
  * ```ts
@@ -38,8 +77,23 @@ export type AndcoSession = {
  * ```
  */
 export interface AndcoCredentials {
-    /** Resolves a token for one Resource Indicator, refreshing lazily when the current one is stale. */
-    accessTokenFor(resource: string): Promise<string | null>;
+    /** Resolves a token for one audience, refreshing or reauthenticating lazily. */
+    accessTokenFor(resource: string, request?: AndcoCredentialRequest): Promise<string | null>;
+    /** Isolates and pins one operation's authority across pages, polling and retries. */
+    forOperation?(): AndcoCredentials;
+    /**
+     * The configuration of the client that issued these credentials, when there is one.
+     *
+     * `andco.with()`, `andco.authorized()` and `service.credentials()` carry it, so a Resource Server
+     * Definition bound to them reads the OAuth `client_id` and API endpoint from here instead of
+     * asking for them a second time. A hand-written resolver may omit it.
+     *
+     * @example
+     * ```ts
+     * const bank = new Bank(andco.with(accessToken)); // clientId and endpoint come from andco.config
+     * ```
+     */
+    readonly config?: AndcoConfig;
 }
 /** Seconds of remaining lifetime under which a token is treated as stale and refreshed. */
 export declare const ANDCO_REFRESH_SKEW_SECONDS = 30;

package/dist/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,kGAAkG;IAClG,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oGAAoG;IACpG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,SAAgC,GAAG,OAAO,CAEpG;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAE9E;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,GAAG,KAAK,IAAI,gBAAgB,CAE/F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAMnF"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;;;;OAOG;IACH,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,kGAAkG;IAClG,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACzD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3F,qFAAqF;IACrF,YAAY,CAAC,IAAI,gBAAgB,CAAC;IAClC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,SAAgC,GAAG,OAAO,CAEpG;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAE9E;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,GAAG,KAAK,IAAI,gBAAgB,CAE/F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAWnF"}

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { type AndcoErrorCode } from "@andco/protocol";
 /**
  * The single error type every Andco operation reports.
  *
@@ -34,7 +35,7 @@ export declare class AndcoError extends Error {
         details?: Readonly<Record<string, unknown>>;
     });
     /** Normalizes anything thrown by a dependency into an `AndcoError`. */
-    static from(cause: unknown, fallbackCode: string): AndcoError;
+    static from(cause: unknown, fallbackCode: SdkErrorCode): AndcoError;
     /** Whether a value is an `AndcoError`. */
     static is(cause: unknown): cause is AndcoError;
 }
@@ -137,29 +138,30 @@ export declare const Result: {
     /** Wraps a value as a successful result. */
     ok<T>(data: T): Result<T>;
     /** Wraps a failure as a result, accepting either a code or an existing error. */
-    fail<T = never>(error: AndcoError | string, options?: {
+    fail<T = never>(error: AndcoError | SdkErrorCode, options?: {
         message?: string;
         status?: number;
         cause?: unknown;
     }): Result<T>;
 };
-/** Error codes the SDK itself raises, as opposed to those relayed from the Authorization Server. */
-export declare const ANDCO_ERROR_CODES: {
-    readonly BROWSER_REQUIRED: "browser_required";
-    readonly BROWSER_UNAVAILABLE: "browser_unavailable";
-    readonly BROWSER_FORBIDDEN: "browser_forbidden";
-    readonly INVALID_CALLBACK: "invalid_callback";
-    readonly INVALID_CONFIGURATION: "invalid_configuration";
-    readonly HANDSHAKE_TIMEOUT: "handshake_timeout";
-    readonly INVALID_IFRAME: "invalid_iframe";
-    readonly INVALID_INTENT_ID: "invalid_intent_id";
-    readonly INVALID_RESPONSE: "invalid_response";
-    readonly POPUP_BLOCKED: "popup_blocked";
-    readonly POPUP_TIMEOUT: "popup_timeout";
-    readonly PRESENTATION_UNSUPPORTED: "presentation_unsupported";
-    readonly SAME_ORIGIN_ENDPOINT: "same_origin_endpoint";
-    readonly SESSION_MISSING: "session_missing";
-    readonly STORAGE_FAILED: "storage_failed";
-    readonly UNTRUSTED_ORIGIN: "untrusted_origin";
-};
+/**
+ * Re-exported so `@andco/sdk` consumers reach the one vocabulary without importing `@andco/protocol`
+ * directly. It used to be a second catalogue declared here, with the same public name as the one in
+ * protocol and different values for the eight conditions both named -- a comparison against the
+ * wrong import never matched, and nothing said which was which.
+ */
+export { ANDCO_ERROR_CODES, type AndcoErrorCode } from "@andco/protocol";
+/**
+ * The vocabulary of codes the SDK may write to `AndcoError.code` on its own initiative — every
+ * member of {@link ANDCO_ERROR_CODES}, derived rather than duplicated.
+ *
+ * This closes the entry points the SDK alone uses to raise its own errors — `AndcoError.from`'s
+ * `fallbackCode` and `Result.fail`'s string shorthand — so a typo or an ad hoc string can no longer
+ * slip in unnoticed. It does not close `AndcoError.code` itself, nor the `AndcoError` constructor:
+ * both must keep accepting a plain `string`, because `AndcoError` is the one error type every Andco
+ * operation reports, including codes this repository does not own — the Authorization Server's own
+ * OAuth error identifiers (RFC 6749) foremost among them — and integrators are expected to construct
+ * one directly for their own domain errors, as `apps/example-oauth-nextjs` already does.
+ */
+export type SdkErrorCode = AndcoErrorCode;
 //# sourceMappingURL=errors.d.ts.map