@kanonak-protocol/sdk 5.38.0 → 6.0.1

package/dist/auth/CredentialProvider.d.ts

@@ -1,65 +1,85 @@
 /**
  * The credential seam between the open protocol layer and a platform's identity
- * mechanism (see ideas/protocol-vs-platform-auth-split.md).
+ * mechanism (see ideas/protocol-vs-platform-auth-split.md, and #126 for its
+ * resource-scoped shape).
  *
  * The protocol layer's entire knowledge of credentials is this interface: given
- * an authority (and any server challenge), a provider returns headers to attach
- * to a request, or declines. How the credential was minted, stored, or proven
- * never crosses this boundary — that is the platform's business.
- */
-/** A fetch that authenticates a request to a publisher/resource host. The
- *  consumption transport produced by {@link createCredentialedFetch} has this
- *  shape; repositories and the server accept it so a host can inject auth. */
-export type AuthenticatedFetchFn = (url: string, publisher: string, method?: string) => Promise<Response>;
-/**
- * What a provider contributes to an outgoing request — scheme-agnostic across
- * header-based credentials (Bearer, DPoP-bound, Basic-wrapped JWT). The protocol
- * layer merges `headers` verbatim and never inspects how they were formed.
+ * the resource being requested (and any server challenge), a provider returns
+ * headers and the scope they are good for, or declines. How the credential was
+ * minted, stored, or proven never crosses this boundary. The provider decides
+ * how wide the scope is; the transport never widens it, attaches the headers
+ * only to URLs inside it, and caches them by it until `expiresAt`.
  *
- * Transport-level mTLS is deliberately NOT expressible here: a client cert is
- * presented in the TLS handshake, not a header. mTLS is an acquisition mechanism
- * (cert → token); consumption uses the minted, header-based credential.
+ * The same shapes are the exec credential helper's wire protocol
+ * ({@link ExecCredentialProvider}), so a helper and an in-process provider are
+ * interchangeable.
  */
-export interface RequestCredential {
-    /** Headers to merge onto the request (e.g. Authorization, plus any proof
-     *  header such as an RFC 9449 DPoP proof). */
-    headers: Record<string, string>;
-    /** Validity of the underlying session credential (NOT the per-request proof
-     *  header), so the consumer can pre-empt re-acquisition before a 401. */
-    expiresAt?: string;
-}
+/** A fetch that authenticates a request. The consumption transport produced by
+ *  {@link createCredentialedFetch} has this shape; repositories and the server
+ *  accept it so a host can inject auth. `publisher` names the package publisher
+ *  the request is for; credentials are chosen by the request URL, not by it. */
+export type AuthenticatedFetchFn = (url: string, publisher: string, method?: string) => Promise<Response>;
 /**
- * A server's authorization challenge, parsed from a 401/403 and forwarded to the
- * provider verbatim. The protocol layer stays dumb: it parses and relays; the
- * provider decides how to satisfy it (bind a nonce, step up, or re-mint).
+ * One challenge from a `WWW-Authenticate` response header (RFC 9110 §11.6.1),
+ * e.g. `Bearer resource_metadata="…", error="invalid_token"`.
  */
 export interface AuthChallenge {
-    /** The raw WWW-Authenticate header value. */
-    wwwAuthenticate: string;
-    /** RFC 9449 server-supplied DPoP nonce, if present, to bind the next proof. */
-    nonce?: string;
-    /** RFC 9470 required assurance (acr_values), if the server demands step-up. */
-    acrValues?: string;
+    /** The auth-scheme as the server spelled it; compare case-insensitively. */
+    scheme: string;
+    /** The auth-params, names lower-cased (RFC 9110: case-insensitive), values unquoted. */
+    params: Record<string, string>;
+    /** A token68 value, for a challenge that carries one instead of auth-params. */
+    token68?: string;
 }
-export interface ResolveOptions {
-    /** The HTTP method of the request being authenticated (for per-request proofs). */
-    method?: string;
-    /** The URL being authenticated (for per-request proofs). */
-    url?: string;
-    /** Re-mint after a server-side revocation — a *stale* credential. */
-    forceRefresh?: boolean;
-    /** The server's challenge from a prior 401/403 on this request. */
-    challenge?: AuthChallenge;
+/** What the transport asks a provider for. */
+export interface CredentialRequest {
+    /** The absolute https URL being requested. */
+    resource: string;
+    /** The request's HTTP method. */
+    method: string;
+    /** The server's challenges, in the order it sent them. Absent when the
+     *  transport asks pre-emptively, for a resource it knows is gated. */
+    challenges?: AuthChallenge[];
 }
+/** A request to forget the credential a server rejected. */
+export interface CredentialEraseRequest extends CredentialRequest {
+    /** The scope of the rejected credential. */
+    scope: string;
+}
+/** A credential: headers, and where they may be attached. */
+export interface Credential {
+    /** Headers merged verbatim onto requests inside `scope` (e.g. Authorization). */
+    headers: Record<string, string>;
+    /** An https origin plus a path prefix, matched on whole path segments. It must
+     *  contain the requested resource. */
+    scope: string;
+    /** When the credential stops being valid, in Unix seconds. Absent: valid for
+     *  as long as this process runs. */
+    expiresAt?: number;
+}
+/** A provider's answer. `declined` means only "no credential for this resource";
+ *  a failure is an exception, never a decline. */
+export type CredentialAnswer = ({
+    status: 'credential';
+} & Credential) | {
+    status: 'declined';
+    reason?: string;
+};
 /**
  * The credential seam. A platform implements this; the protocol layer only calls
- * it. Returns null to decline (anonymous / not this provider's authority).
- *
- * `forceRefresh` ("the credential is stale — mint the same kind") is distinct
- * from a `challenge` carrying `acrValues` ("the credential is insufficient —
- * acquire a stronger one"). Keeping them separate lets the provider tell those
- * apart; a binary drop-and-retry cannot.
+ * it. `get` answers for a resource; `erase` forgets a credential the server
+ * rejected (401), before the transport asks once more. A server that finds a
+ * credential valid but insufficient (403 with `error="insufficient_scope"`) gets
+ * `get` with its challenge and no `erase`: the credential still serves the rest
+ * of its scope.
  */
 export interface CredentialProvider {
-    resolve(authority: string, opts?: ResolveOptions): Promise<RequestCredential | null>;
+    get(request: CredentialRequest): Promise<CredentialAnswer>;
+    erase(request: CredentialEraseRequest): Promise<void>;
+}
+/** A request that could not be authenticated: a provider failed, declined a
+ *  resource that requires a credential, answered outside the protocol, or a
+ *  server rejected the credential it answered with. Never silently anonymous. */
+export declare class CredentialError extends Error {
+    constructor(message: string);
 }

package/dist/auth/ExecCredentialProvider.d.ts

@@ -0,0 +1,55 @@
+import type { Writable } from 'node:stream';
+import { type CredentialAnswer, type CredentialEraseRequest, type CredentialProvider, type CredentialRequest } from './CredentialProvider.js';
+/** How long a helper may run before it is stopped. */
+export declare const CREDENTIAL_HELPER_TIMEOUT_MS = 120000;
+export interface ExecCredentialProviderOptions {
+    /** The helper's command line. It is split on whitespace and run without a
+     *  shell (as Go's GOAUTH runs its commands); the operation, `get` or `erase`,
+     *  is appended as the last argument. */
+    command: string;
+    /** Whether the helper may interact with the user; sent as `interactive`. */
+    interactive?: boolean;
+    /** Milliseconds a helper may run; {@link CREDENTIAL_HELPER_TIMEOUT_MS} by default. */
+    timeoutMs?: number;
+    /** Where the helper's stderr is shown as it runs; `process.stderr` by default. */
+    stderr?: Writable;
+    /** The clock, in Unix seconds. */
+    nowSeconds?: () => number;
+}
+/**
+ * A {@link CredentialProvider} that is a separate program: the exec credential
+ * helper protocol (#126), the shape git, docker, cargo (RFC 3139), kubectl and
+ * Bazel credential helpers share.
+ *
+ * The provider runs `<command> get` or `<command> erase`, writes one JSON
+ * request to its stdin, and reads one JSON answer from its stdout:
+ *
+ *   request  {"version": 1, "operation": "get" | "erase", "resource": URL,
+ *             "method": "GET", "challenges"?: [{scheme, params, token68?}],
+ *             "scope"?: (erase: the rejected credential's scope), "interactive": bool}
+ *   get      {"version": 1, "status": "credential", "headers": {...},
+ *             "scope": "https://host/prefix", "expiresAt"?: unix-seconds}
+ *         or {"version": 1, "status": "declined", "reason"?: "..."}
+ *   erase    {"version": 1, "status": "erased"}
+ *
+ * A non-zero exit, a timeout, or an answer outside the protocol is a
+ * {@link CredentialError} carrying the helper's stderr; nothing falls back to
+ * anonymous. The helper's stderr is also shown as it runs. Requests and answers
+ * are never logged: they carry credentials.
+ */
+export declare class ExecCredentialProvider implements CredentialProvider {
+    private readonly argv;
+    private readonly interactive;
+    private readonly timeoutMs;
+    private readonly stderr;
+    private readonly now;
+    constructor(opts: ExecCredentialProviderOptions);
+    /** The command line as configured. */
+    get command(): string;
+    get(request: CredentialRequest): Promise<CredentialAnswer>;
+    erase(request: CredentialEraseRequest): Promise<void>;
+    private wireRequest;
+    private run;
+}
+/** A helper command line split the way it is run: on whitespace, no quoting. */
+export declare function splitCommandLine(command: string): string[];

package/dist/auth/OAuthDiscovery.d.ts

@@ -1,3 +1,14 @@
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728), as validated by
+ * {@link OAuthDiscovery}: only documents whose `resource` checks out are returned.
+ */
+export interface ProtectedResourceMetadata {
+    /** The protected resource's identifier (`resource`). */
+    resource: string;
+    /** Issuer identifiers of the authorization servers that protect it
+     *  (`authorization_servers`; empty when the document names none). */
+    authorizationServers: string[];
+}
 /**
  * OAuth 2.0 Authorization Server Metadata (RFC 8414).
  */
@@ -44,18 +55,35 @@ export declare const DEFAULT_CONSENT_BINDING_PARAM = "key_thumbprint";
  */
 export declare class OAuthDiscovery {
     private readonly cache;
-    private readonly prCache;
+    private readonly wellKnownCache;
+    private readonly metadataUrlCache;
+    /**
+     * RFC 9728 §3.1: the metadata of the resource `identifier` (an https URL, e.g.
+     * an origin), at its well-known URL: `/.well-known/oauth-protected-resource`
+     * inserted between the host and the identifier's path. Validated per §3.3:
+     * the document's `resource` must be identical to `identifier` (compared after
+     * URL normalization, so `https://h` and `https://h/` are one identifier).
+     *
+     * null when the resource does not advertise metadata there: a 404 or 410, a
+     * redirect (metadata for an origin is served by that origin), or a 200 that is
+     * not a JSON document (static hosts answer unknown paths with an HTML page).
+     * Throws a `KanonakHttpError` for any other status, including 401/403 (the
+     * host gates even its metadata), and an `Error` for a JSON document that
+     * fails validation, which RFC 9728 forbids using.
+     */
+    protectedResourceMetadata(identifier: string): Promise<ProtectedResourceMetadata | null>;
     /**
-     * RFC 9728 (OAuth 2.0 Protected Resource Metadata): the authorization
-     * server(s) that protect a resource host. The git credential helper uses this
-     * to resolve a git/registry host → its Kanonak authority (issuer URLs in
-     * `authorization_servers`); RFC 8414 on that authority then yields the session
-     * endpoint. Returns null when the host advertises no protected-resource
-     * metadata — i.e. it isn't a Kanonak-credentialed host, so the helper declines
-     * and git falls through. Quiet on misses (the helper probes every host git
-     * asks about, most of which won't be Kanonak resources).
+     * RFC 9728 §5.1: the metadata at the URL a challenge's `resource_metadata`
+     * parameter names, for the request to `requestedUrl` that drew the challenge.
+     * §3.3 requires its `resource` to match the requested URL. A resource
+     * identifier covers every URL beneath it, so this checks that `requestedUrl`
+     * lies inside `resource`: same origin, on whole path segments (the reading
+     * deployed clients use). Throws when the document is missing, is not JSON,
+     * or fails that check.
      */
-    discoverProtectedResource(resourceHost: string): Promise<string[] | null>;
+    protectedResourceMetadataAt(metadataUrl: string, requestedUrl: string): Promise<ProtectedResourceMetadata>;
+    private fetchWellKnown;
+    private fetchMetadataAt;
     discover(host: string): Promise<OAuthServerMetadata | null>;
     supportsOAuth(host: string): Promise<boolean>;
     static supportsPkceS256(m: OAuthServerMetadata): boolean;

package/dist/auth/TokenCredentialProvider.d.ts

@@ -1,4 +1,5 @@
-import type { CredentialProvider, RequestCredential, ResolveOptions } from './CredentialProvider.js';
+import type { CredentialAnswer, CredentialProvider, CredentialRequest } from './CredentialProvider.js';
+import { OAuthDiscovery } from './OAuthDiscovery.js';
 /**
  * Reference / BYO-token credential provider — the open layer's minimal way to
  * consume a gated package without any platform tooling. It reads a token from
@@ -6,11 +7,18 @@ import type { CredentialProvider, RequestCredential, ResolveOptions } from './Cr
  *
  * `Bearer` here is only the *transport* of whatever the issuer minted — its
  * security properties are the issuer's choice, not the protocol's. A platform
- * ships a stronger, sender-constrained provider (e.g. a DPoP-bound JWT minted
- * from a device cert); this one keeps the open SDK/CLI usable standalone, e.g.
- * for an enterprise pointing at its own OAuth-issued token, or for CI.
+ * supplies a stronger provider, in process or as an exec credential helper;
+ * this one keeps the open SDK/CLI usable standalone, e.g. for an enterprise
+ * pointing at its own OAuth-issued token, or for CI.
  *
- * Token sources, in precedence order, per authority host:
+ * A token is presented only to a resource that names its authorization server
+ * in validated RFC 9728 metadata: from the challenge's `resource_metadata`, or
+ * else at the resource origin's well-known URL. The credential's scope is that
+ * metadata's `resource`, so the token is attached nowhere else. A resource with
+ * no such metadata is declined.
+ *
+ * Token sources, in precedence order, per authorization-server host (the first
+ * of the resource's `authorization_servers` that has one):
  *   1. an explicit `tokens` map
  *   2. env `KANONAK_TOKEN_<AUTHORITY>` (host upper-cased, non-alphanumeric → `_`)
  *   3. env `KANONAK_TOKEN` (applies to any authority)
@@ -20,10 +28,22 @@ export interface TokenCredentialProviderOptions {
     tokens?: Record<string, string>;
     /** Environment to read from; defaults to `process.env` when available. */
     env?: Record<string, string | undefined>;
+    /** RFC 9728 discovery; a fresh {@link OAuthDiscovery} by default. */
+    discovery?: Pick<OAuthDiscovery, 'protectedResourceMetadata' | 'protectedResourceMetadataAt'>;
 }
+/** The environment variable a BYO token is read from, and the prefix of its
+ *  per-authority form. */
+export declare const TOKEN_ENV = "KANONAK_TOKEN";
+/** `KANONAK_TOKEN_<AUTHORITY>` for an authorization-server host. */
+export declare function tokenEnvKeyFor(authority: string): string;
 export declare class TokenCredentialProvider implements CredentialProvider {
     private readonly tokens;
     private readonly env;
+    private readonly discovery;
     constructor(opts?: TokenCredentialProviderOptions);
-    resolve(authority: string, _opts?: ResolveOptions): Promise<RequestCredential | null>;
+    get(request: CredentialRequest): Promise<CredentialAnswer>;
+    /** A configured token cannot be erased; the transport asks once more, gets the
+     *  same token, and reports the server's second rejection. */
+    erase(): Promise<void>;
+    private metadataFor;
 }

package/dist/auth/challenges.d.ts

@@ -0,0 +1,17 @@
+import type { AuthChallenge } from './CredentialProvider.js';
+/**
+ * Parse a `WWW-Authenticate` field value into its challenges (RFC 9110 §11.6.1):
+ *
+ *   WWW-Authenticate = #challenge
+ *   challenge        = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
+ *   auth-param       = token BWS "=" BWS ( token / quoted-string )
+ *   token68          = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"="
+ *
+ * Several header lines arrive joined with ", " (the Fetch `Headers` contract),
+ * which is the same list syntax, so one value covers them all. Challenges keep
+ * the server's order. Parameter names are lower-cased, because RFC 9110 makes
+ * them case-insensitive; the scheme keeps the server's spelling (compare it
+ * case-insensitively). A malformed value, or a parameter repeated within one
+ * challenge, throws: a challenge we cannot read is not one we can act on.
+ */
+export declare function parseWwwAuthenticate(value: string): AuthChallenge[];

package/dist/auth/credentialAnswer.d.ts

@@ -0,0 +1,34 @@
+import type { CredentialAnswer, CredentialRequest } from './CredentialProvider.js';
+/** The exec credential helper protocol version this SDK speaks (#126). */
+export declare const CREDENTIAL_HELPER_PROTOCOL_VERSION = 1;
+/** Why an answer was refused. Stable: the conformance vectors pin them. */
+export type AnswerProblem = 'malformed' | 'version' | 'status' | 'headers' | 'scope' | 'scope-excludes-resource' | 'expires-at' | 'expired' | 'reason';
+export type AnswerCheck<T> = {
+    ok: true;
+    answer: T;
+} | {
+    ok: false;
+    problem: AnswerProblem;
+    message: string;
+};
+/**
+ * Check a provider's answer to `request` against the protocol, for any provider,
+ * in-process or exec. A credential must:
+ *  - carry at least one header, each a valid field name with a value free of
+ *    CR, LF and NUL;
+ *  - name a scope that is an https origin plus a path prefix (no userinfo, query
+ *    or fragment) and that contains the requested resource;
+ *  - when it has `expiresAt` (Unix seconds), not be expired at `nowSeconds`.
+ * A decline may carry a string `reason`. Fields the protocol does not define
+ * are ignored, so a newer provider can add some.
+ */
+export declare function checkCredentialAnswer(request: CredentialRequest, value: unknown, nowSeconds: number): AnswerCheck<CredentialAnswer>;
+/** {@link checkCredentialAnswer} for a helper's wire answer, which also carries
+ *  `"version": 1`. */
+export declare function checkHelperAnswer(request: CredentialRequest, value: unknown, nowSeconds: number): AnswerCheck<CredentialAnswer>;
+/** A helper's answer to `erase`: exactly `{"version": 1, "status": "erased"}`
+ *  (other fields ignored). Erasing a credential the helper no longer holds is
+ *  still "erased". */
+export declare function checkHelperEraseAnswer(value: unknown): AnswerCheck<{
+    status: 'erased';
+}>;

package/dist/auth/credentialConfig.d.ts

@@ -0,0 +1,32 @@
+import type { CredentialProvider } from './CredentialProvider.js';
+import type { OAuthDiscovery } from './OAuthDiscovery.js';
+/** The environment variable naming a credential helper's command line. */
+export declare const CREDENTIAL_HELPER_ENV = "KANONAK_CREDENTIAL_HELPER";
+/** The user-level config file: `~/.kanonak/config.json`. */
+export declare function userConfigPath(): string;
+export interface CredentialProviderConfigOptions {
+    /** Environment to read; `process.env` by default. */
+    env?: Record<string, string | undefined>;
+    /** The user config file; {@link userConfigPath} by default. */
+    configPath?: string;
+    /** Whether a helper may interact with the user. */
+    interactive?: boolean;
+    /** RFC 9728 discovery shared with the transport. */
+    discovery?: Pick<OAuthDiscovery, 'protectedResourceMetadata' | 'protectedResourceMetadataAt'>;
+}
+/**
+ * The credential provider the user configured, from user-level sources only.
+ * Nothing in a workspace or repository can name a helper: that would let a
+ * cloned repository choose a command the CLI runs.
+ *
+ *  - A credential helper's command line, from `KANONAK_CREDENTIAL_HELPER`, or
+ *    else `credentialHelper` in `~/.kanonak/config.json` (the file configures an
+ *    environment without setting any variable in it). It becomes an
+ *    {@link ExecCredentialProvider}.
+ *  - Otherwise the {@link TokenCredentialProvider}, reading `KANONAK_TOKEN` and
+ *    `KANONAK_TOKEN_<AUTHORITY>`.
+ *
+ * A helper together with any `KANONAK_TOKEN*` variable is an error that names
+ * both: two credential mechanisms with no rule between them is ambiguous.
+ */
+export declare function credentialProviderFromConfig(opts?: CredentialProviderConfigOptions): CredentialProvider;

package/dist/auth/credentialedFetch.d.ts

@@ -1,29 +1,40 @@
-import type { AuthenticatedFetchFn, AuthChallenge, CredentialProvider } from './CredentialProvider.js';
-/**
- * Parse a server's authorization challenge from a 401/403 response. Returns
- * undefined when the response carries no challenge (a plain unauthorized).
- */
-export declare function parseAuthChallenge(res: Response): AuthChallenge | undefined;
+import { type AuthenticatedFetchFn, type CredentialProvider } from './CredentialProvider.js';
+import { OAuthDiscovery } from './OAuthDiscovery.js';
+/** A cached credential is not attached within this many seconds of its `expiresAt`. */
+export declare const CREDENTIAL_EXPIRY_SKEW_SECONDS = 30;
 export interface CredentialedFetchDeps {
-    discovery?: {
-        discoverProtectedResource(host: string): Promise<string[] | null>;
-    };
+    /** RFC 9728 discovery, used to learn that an origin is gated before asking it
+     *  anything (see {@link createCredentialedFetch}). */
+    discovery?: Pick<OAuthDiscovery, 'protectedResourceMetadata'>;
+    /** The clock, in Unix seconds. */
+    nowSeconds?: () => number;
 }
 /**
- * The protocol's consumption transport. Given a {@link CredentialProvider}, it:
+ * The protocol's consumption transport (#126). Given a {@link CredentialProvider}:
  *
- *   1. Discovers whether a host is gated and, if so, its authority (RFC 9728).
- *   2. Asks the provider for a credential for that authority and attaches the
- *      returned headers. A public host, or a provider that declines, → anonymous.
- *   3. Never blind-follows a gated redirect (`redirect: 'manual'`), which would
- *      otherwise loop into a login.
- *   4. On a 401/403 to an authenticated request, parses the server challenge
- *      and re-resolves: with a `challenge` the provider binds a nonce or steps
- *      up; with no challenge the credential is treated as stale and re-minted
- *      (`forceRefresh`). Retries once, then surfaces the failure.
+ *  1. A credential cached for a scope that contains the URL (the narrowest one,
+ *     not within {@link CREDENTIAL_EXPIRY_SKEW_SECONDS} of expiring) is attached.
+ *     Headers are attached only inside their scope, so a redirect to another
+ *     origin, or a lock entry naming another host, never carries them.
+ *  2. With none cached, an origin known to be gated is asked pre-emptively, with
+ *     no challenge. An origin is known to be gated once it has challenged in
+ *     this process, or when it advertises RFC 9728 metadata (or gates even
+ *     that). Discovery is what reaches a server that answers anonymous clients
+ *     with 404 rather than a challenge.
+ *  3. A 401 is answered with the server's challenges: the rejected credential,
+ *     if one was attached, is erased, and the provider is asked once more. A 403
+ *     whose challenge says `insufficient_scope` is asked once more without an
+ *     erase, since the credential still serves the rest of its scope. Any other
+ *     403 is a refusal, returned to the caller to report.
+ *  4. A second rejection, a decline when the server requires a credential, a
+ *     provider failure, an answer outside the protocol, or a gated resource with
+ *     no provider configured throws a {@link CredentialError}. Nothing falls back
+ *     to anonymous.
  *
- * Without a provider it runs fully anonymous (public packages still resolve).
- * Discovery results and credentials are cached per host/authority so one
- * install/connect doesn't re-discover or re-mint for every package in a closure.
+ * Redirects are never followed blindly (`redirect: 'manual'`); the caller sees
+ * the 3xx and fetches the new location through this transport again. Provider
+ * calls are serialized per origin, and each re-checks the cache first, so a
+ * closure fetched concurrently asks once per scope rather than once per URL.
+ * Without a provider every request is anonymous, and a gated one fails loudly.
  */
 export declare function createCredentialedFetch(provider?: CredentialProvider, deps?: CredentialedFetchDeps): AuthenticatedFetchFn;

package/dist/auth/index.d.ts

@@ -1,8 +1,14 @@
 export { normalizeHost } from './hosts.js';
 export { OAuthDiscovery, DEFAULT_CONSENT_BINDING_PARAM } from './OAuthDiscovery.js';
-export type { OAuthServerMetadata } from './OAuthDiscovery.js';
-export type { AuthenticatedFetchFn, CredentialProvider, RequestCredential, AuthChallenge, ResolveOptions, } from './CredentialProvider.js';
-export { createCredentialedFetch, parseAuthChallenge } from './credentialedFetch.js';
+export type { OAuthServerMetadata, ProtectedResourceMetadata } from './OAuthDiscovery.js';
+export { CredentialError } from './CredentialProvider.js';
+export type { AuthenticatedFetchFn, AuthChallenge, Credential, CredentialAnswer, CredentialEraseRequest, CredentialProvider, CredentialRequest, } from './CredentialProvider.js';
+export { createCredentialedFetch, CREDENTIAL_EXPIRY_SKEW_SECONDS } from './credentialedFetch.js';
 export type { CredentialedFetchDeps } from './credentialedFetch.js';
-export { TokenCredentialProvider } from './TokenCredentialProvider.js';
+export { parseWwwAuthenticate } from './challenges.js';
+export { parseScope, scopeContains, narrowestScope } from './scope.js';
+export type { ParsedScope } from './scope.js';
+export { CREDENTIAL_HELPER_PROTOCOL_VERSION, checkCredentialAnswer, checkHelperAnswer, checkHelperEraseAnswer, } from './credentialAnswer.js';
+export type { AnswerCheck, AnswerProblem } from './credentialAnswer.js';
+export { TokenCredentialProvider, TOKEN_ENV, tokenEnvKeyFor } from './TokenCredentialProvider.js';
 export type { TokenCredentialProviderOptions } from './TokenCredentialProvider.js';

package/dist/auth/scope.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Credential scopes (#126). A scope is an `https` origin plus a path prefix,
+ * e.g. `https://registry.example.net/example.com` or `https://example.com/`. A
+ * credential's headers are attached only to URLs inside its scope, so a
+ * redirect to another origin, or a lock entry naming another host, never
+ * carries them. The prefix matches whole path segments: `/example.com` covers
+ * `/example.com` and `/example.com/core/1.0.0.kan.yml`, never
+ * `/example.com.evil/…`.
+ */
+export interface ParsedScope {
+    /** `https://host[:port]` */
+    origin: string;
+    /** The path prefix, normalized to end in `/`. */
+    prefix: string;
+}
+/**
+ * Parse and check a scope. Throws when it is not an absolute `https` URL, or
+ * carries credentials, a query or a fragment: none of those can bound a path
+ * prefix.
+ */
+export declare function parseScope(scope: string): ParsedScope;
+/**
+ * Whether `url` lies inside `scope`: same origin, and its path is the scope's
+ * path or continues it at a segment boundary. A non-https URL is never inside.
+ */
+export declare function scopeContains(scope: string | ParsedScope, url: string): boolean;
+/** Of the scopes that contain `url`, the most specific (longest prefix), or undefined. */
+export declare function narrowestScope<T extends {
+    scope: string;
+}>(entries: Iterable<T>, url: string): T | undefined;

package/dist/browser.d.ts

@@ -34,9 +34,11 @@ export type { CanonicalInput, CanonicalInputSubject, CanonicalInputStatement, Ca
 export { buildOntologyModel } from './introspection/index.js';
 export type { OntologyModel, ClassDef, PropertyDef, ClassRef, TypeRef, BuildOntologyModelOptions, } from './introspection/index.js';
 export { normalizeHost } from './auth/hosts.js';
-export { OAuthDiscovery, createCredentialedFetch, parseAuthChallenge, TokenCredentialProvider, } from './auth/index.js';
-export type { AuthenticatedFetchFn, CredentialProvider, RequestCredential, AuthChallenge, ResolveOptions, } from './auth/index.js';
+export { OAuthDiscovery, CredentialError, createCredentialedFetch, CREDENTIAL_EXPIRY_SKEW_SECONDS, parseWwwAuthenticate, parseScope, scopeContains, narrowestScope, CREDENTIAL_HELPER_PROTOCOL_VERSION, checkCredentialAnswer, checkHelperAnswer, checkHelperEraseAnswer, TokenCredentialProvider, TOKEN_ENV, tokenEnvKeyFor, } from './auth/index.js';
+export type { AuthenticatedFetchFn, AuthChallenge, Credential, CredentialAnswer, CredentialEraseRequest, CredentialProvider, CredentialRequest, CredentialedFetchDeps, ParsedScope, AnswerCheck, AnswerProblem, ProtectedResourceMetadata, TokenCredentialProviderOptions, } from './auth/index.js';
 export { kanonakFetch, setKanonakUserAgent, getKanonakUserAgent, KANONAK_USER_AGENT, } from './http/kanonakFetch.js';
+export { KanonakHttpError, httpError, describeResponse, retryAfterSecondsOf } from './http/HttpError.js';
+export type { ProblemDetails } from './http/HttpError.js';
 export { parseLockFile, serializeLockFile, computeIntegrityAsync, INTEGRITY_PREFIX, } from './lock/LockFile.js';
 export type { LockFile, LockEntry } from './lock/LockFile.js';
 export { PackageBuilder, ImportBook, contentAddressedName, sanitizeName, ProducerRepository, EntitlementProducer, EntitlementDeniedError, allowAllPolicy, noopMeter, } from './producer/index.js';

package/dist/browser.js

@@ -1 +1 @@
-import{a as $,b as ee,c as oe,d as Ue,f as Be,g as we,h as Ge,i as qe}from"./chunk-LBVHWFFL.js";import{a as ze}from"./chunk-ED35OFGD.js";import{a as ve,b as He,c as Te,d as Le,e as Me,f as _e,g as Fe,h as We,i as Ye,j as Xe,k as Je,l as Qe}from"./chunk-ADSDFJUO.js";import{a as c,b as m,c as u,e as d,h as f,j as y,k as R,l as k,m as x,n as P,o as g}from"./chunk-OOYGILH4.js";import{a as re,b as te,c as ne}from"./chunk-GKIX3OD6.js";import{a as ae}from"./chunk-D2X6J77P.js";import"./chunk-SC5M74NM.js";import{A as be,B as Ae,C as Oe,M as Ne,a as ie,b as se,c as pe,d as le,g as ce,h as me,i as ue,j as de,l as fe,m as ye,n as Re,o as ke,p as xe,q as Pe,r as ge,s as Se,t as Ce,u as Ee,v as Ie,w as Ke,x as he,y as je,z as De}from"./chunk-O6SOU5Y2.js";import"./chunk-VORVR5BZ.js";import{m as Ve}from"./chunk-TYVZXABI.js";import"./chunk-QHABFCRC.js";import{a as p}from"./chunk-6VIUXP4N.js";import{a as X,g as J,h as Q,k as Z}from"./chunk-22DSABP6.js";import{a as l}from"./chunk-7JBKOJB4.js";import"./chunk-PEJALHXK.js";import{a as T,b as L,h as F,i as U,j as B,k as w,ka as q,l as G,ma as z}from"./chunk-NUTHBBDZ.js";import{I as W,J as Y,a as S,b as C,c as E,d as I,e as h,g as j,h as D,i as b,j as A,k as O,l as V,m as N,n as v,o as H,u as M,v as _}from"./chunk-D4QGPMRW.js";import{a as K}from"./chunk-FUUTGGJS.js";import"./chunk-F67UH4FD.js";import{c as e,d as o,e as r,f as t,g as n,h as a,i,k as s}from"./chunk-QILEJIFU.js";export{Ie as AmbiguousReferenceRule,O as BooleanStatement,Te as CANONICAL_FORM_VERSION,J as Carrier,Ae as ClassDefinitionRule,ke as ClassHierarchyCycleRule,C as DefinedKanonak,ee as EdgeType,I as EmbeddedKanonak,fe as EmbeddedKanonakTypeRule,N as EmbeddedStatement,Je as EntitlementDeniedError,Qe as EntitlementProducer,oe as GraphBuilder,g as HttpKanonakDocumentRepository,y as INTEGRITY_PREFIX,_e as ImportBook,ye as ImportExistenceRule,p as InMemoryKanonakDocumentRepository,c as KANONAK_USER_AGENT,S as Kanonak,te as KanonakDocumentPositions,Z as KanonakObjectParser,Ne as KanonakObjectValidator,l as KanonakParser,K as KanonakUri,ae as KanonakUriBuilder,q as KanonakVocabulary,v as ListStatement,Oe as MarkdownLinkRule,H as MarkdownStatement,Ce as NamespaceImportCycleRule,ce as NamespacePrefixRule,$ as NodeType,A as NumberStatement,Be as OAuthDiscovery,he as ObjectPropertyValueValidationRule,pe as OntologyValidationError,ie as OntologyValidationResult,Le as PackageBuilder,We as ProducerRepository,je as PropertyDomainRule,xe as PropertyHierarchyCycleRule,De as PropertyKindRangeConsistencyRule,re as PropertyMetadata,Ke as PropertyRangeReferenceRule,Pe as PropertyRangeRequiredRule,ue as PropertyTypeSpecificityRule,f as PublisherConfigResolver,P as PublisherIndex,h as ReferenceKanonak,V as ReferenceStatement,be as ReservedNameShadowRule,me as ResourceNamingRule,T as ResourceResolver,z as ResourceTypeClassifier,U as SHACL_PACKAGE,F as SHACL_PUBLISHER,w as SH_NODE_SHAPE,G as SH_PROPERTY_SHAPE,B as SH_SHAPE,D as ScalarStatement,j as Statement,b as StringStatement,ge as SubClassOfReferenceRule,Se as SubPropertyOfReferenceRule,E as SubjectKanonak,de as SubjectKanonakTypeRequiredRule,qe as TokenCredentialProvider,L as TypeResolver,Ee as UnresolvedPredicateRule,Re as UnresolvedReferenceRule,le as ValidationContext,se as ValidationSeverity,Ye as allowAllPolicy,Ve as buildOntologyModel,ve as canonicalForm,He as canonicalHash,Q as carrierOf,e as compareVersions,x as computeIntegrityAsync,Me as contentAddressedName,Ge as createCredentialedFetch,t as createVersion,ze as findDerivation,r as formatVersion,u as getKanonakUserAgent,a as isCompatibleVersion,i as isMajorCompatible,d as kanonakFetch,Xe as noopMeter,Ue as normalizeHost,we as parseAuthChallenge,R as parseLockFile,n as parseVersionString,ne as parseWithPositions,s as pickHighestDocument,_ as referenceUris,Fe as sanitizeName,k as serializeLockFile,m as setKanonakUserAgent,Y as subjectAddress,M as typeReferenceUris,W as valuesOf,o as versionsEqual,X as walkDefinedKanonaks};
+import{a as ne,b as ae,c as ie,d as We,e as ze,f as Ye,g as Xe,i as Je,j as Qe,k as Ze,l as $e,m as eo,n as oo,o as ro,p as to,q as no,r as ao,s as io}from"./chunk-PNBTIGX7.js";import{a as so}from"./chunk-ED35OFGD.js";import{a as we,b as Me,c as Fe,d as Ue,e as Be,f as Ge,g as qe,h as po,i as lo,j as co,k as mo,l as uo}from"./chunk-ADSDFJUO.js";import{a as c,b as m,c as d,d as u,e as R,f,g as y,h as k,j as x,m as P,o as E,p as C,q as S,r as g,s as I,t as K}from"./chunk-HKQTB65D.js";import{a as se,b as pe,c as le}from"./chunk-GKIX3OD6.js";import{a as ce}from"./chunk-D2X6J77P.js";import"./chunk-SC5M74NM.js";import{A as He,B as Te,C as ve,M as Le,a as me,b as de,c as ue,d as Re,g as fe,h as ye,i as ke,j as xe,l as Pe,m as Ee,n as Ce,o as Se,p as ge,q as Ie,r as Ke,s as he,t as Ae,u as Oe,v as De,w as be,x as je,y as Ne,z as Ve}from"./chunk-O6SOU5Y2.js";import"./chunk-VORVR5BZ.js";import{m as _e}from"./chunk-TYVZXABI.js";import"./chunk-QHABFCRC.js";import{a as p}from"./chunk-6VIUXP4N.js";import{a as ee,g as oe,h as re,k as te}from"./chunk-22DSABP6.js";import{a as l}from"./chunk-7JBKOJB4.js";import"./chunk-PEJALHXK.js";import{a as F,b as U,h as q,i as W,j as z,k as Y,ka as J,l as X,ma as Q}from"./chunk-NUTHBBDZ.js";import{I as Z,J as $,a as h,b as A,c as O,d as D,e as j,g as N,h as V,i as H,j as T,k as v,l as _,m as L,n as w,o as M,u as B,v as G}from"./chunk-D4QGPMRW.js";import{a as b}from"./chunk-FUUTGGJS.js";import"./chunk-F67UH4FD.js";import{c as e,d as o,e as r,f as t,g as n,h as a,i,k as s}from"./chunk-QILEJIFU.js";export{De as AmbiguousReferenceRule,v as BooleanStatement,Fe as CANONICAL_FORM_VERSION,ro as CREDENTIAL_EXPIRY_SKEW_SECONDS,Qe as CREDENTIAL_HELPER_PROTOCOL_VERSION,oe as Carrier,Te as ClassDefinitionRule,Se as ClassHierarchyCycleRule,R as CredentialError,A as DefinedKanonak,ae as EdgeType,D as EmbeddedKanonak,Pe as EmbeddedKanonakTypeRule,L as EmbeddedStatement,mo as EntitlementDeniedError,uo as EntitlementProducer,ie as GraphBuilder,K as HttpKanonakDocumentRepository,E as INTEGRITY_PREFIX,Ge as ImportBook,Ee as ImportExistenceRule,p as InMemoryKanonakDocumentRepository,f as KANONAK_USER_AGENT,h as Kanonak,pe as KanonakDocumentPositions,c as KanonakHttpError,te as KanonakObjectParser,Le as KanonakObjectValidator,l as KanonakParser,b as KanonakUri,ce as KanonakUriBuilder,J as KanonakVocabulary,w as ListStatement,ve as MarkdownLinkRule,M as MarkdownStatement,Ae as NamespaceImportCycleRule,fe as NamespacePrefixRule,ne as NodeType,T as NumberStatement,Je as OAuthDiscovery,je as ObjectPropertyValueValidationRule,ue as OntologyValidationError,me as OntologyValidationResult,Ue as PackageBuilder,po as ProducerRepository,Ne as PropertyDomainRule,ge as PropertyHierarchyCycleRule,Ve as PropertyKindRangeConsistencyRule,se as PropertyMetadata,be as PropertyRangeReferenceRule,Ie as PropertyRangeRequiredRule,ke as PropertyTypeSpecificityRule,P as PublisherConfigResolver,I as PublisherIndex,j as ReferenceKanonak,_ as ReferenceStatement,He as ReservedNameShadowRule,ye as ResourceNamingRule,F as ResourceResolver,Q as ResourceTypeClassifier,W as SHACL_PACKAGE,q as SHACL_PUBLISHER,Y as SH_NODE_SHAPE,X as SH_PROPERTY_SHAPE,z as SH_SHAPE,V as ScalarStatement,N as Statement,H as StringStatement,Ke as SubClassOfReferenceRule,he as SubPropertyOfReferenceRule,O as SubjectKanonak,xe as SubjectKanonakTypeRequiredRule,no as TOKEN_ENV,io as TokenCredentialProvider,U as TypeResolver,Oe as UnresolvedPredicateRule,Ce as UnresolvedReferenceRule,Re as ValidationContext,de as ValidationSeverity,lo as allowAllPolicy,_e as buildOntologyModel,we as canonicalForm,Me as canonicalHash,re as carrierOf,Ze as checkCredentialAnswer,$e as checkHelperAnswer,eo as checkHelperEraseAnswer,e as compareVersions,g as computeIntegrityAsync,Be as contentAddressedName,to as createCredentialedFetch,t as createVersion,d as describeResponse,so as findDerivation,r as formatVersion,k as getKanonakUserAgent,m as httpError,a as isCompatibleVersion,i as isMajorCompatible,x as kanonakFetch,Xe as narrowestScope,co as noopMeter,We as normalizeHost,C as parseLockFile,ze as parseScope,n as parseVersionString,le as parseWithPositions,oo as parseWwwAuthenticate,s as pickHighestDocument,G as referenceUris,u as retryAfterSecondsOf,qe as sanitizeName,Ye as scopeContains,S as serializeLockFile,y as setKanonakUserAgent,$ as subjectAddress,ao as tokenEnvKeyFor,B as typeReferenceUris,Z as valuesOf,o as versionsEqual,ee as walkDefinedKanonaks};