@hivemagnus/hive-common 0.0.0-stage → 0.2.0

package/dist/node-http/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `node:http` adapters: the same request context, Oathweave auth, error envelope and health
+ * routes as `/hono`, for services built on a plain `http.createServer()`.
+ *
+ *   const server = http.createServer(hiveHandler(async (req, res) => {
+ *     const principal = await authenticate(req, verifier);
+ *     sendJson(res, 200, { hello: principal.subject });
+ *   }, { health: { checks }, logger }));
+ */
+import type { IncomingMessage, RequestListener, ServerResponse } from 'node:http';
+import { type CreateRequestContextOptions, type RequestContext } from '../context/index.js';
+import { type Health, type HealthOptions } from '../health/index.js';
+import type { Logger } from '../log/index.js';
+import type { OathweavePrincipal } from '../oathweave/claims.js';
+import type { OathweaveVerifier, VerifyOptions } from '../oathweave/verifier.js';
+export declare function requestContextFor(req: IncomingMessage, options?: CreateRequestContextOptions): RequestContext;
+/** Verify the request's `Authorization: Bearer` header and record the principal on the context. */
+export declare function authenticate(req: IncomingMessage, verifier: OathweaveVerifier, options?: VerifyOptions): Promise<OathweavePrincipal>;
+/** Send a JSON body with `no-store` caching. */
+export declare function sendJson(res: ServerResponse, status: number, body: unknown, headers?: Readonly<Record<string, string>>): void;
+export interface SendErrorOptions {
+    readonly requestId?: string | undefined;
+    readonly logger?: Pick<Logger, 'error'>;
+}
+/** Send any thrown value as the error envelope. Non-HiveErrors become a logged, generic 500. */
+export declare function sendError(res: ServerResponse, error: unknown, options?: SendErrorOptions): void;
+/**
+ * Serve a health path. Returns true when `req` was a health request and has been answered.
+ * The liveness body is the one `health` was created with (see `liveBody`).
+ */
+export declare function handleHealth(req: IncomingMessage, res: ServerResponse, health: Health<object>): Promise<boolean>;
+export interface HiveHandlerOptions extends CreateRequestContextOptions {
+    /** Serve health endpoints before `handler` runs. */
+    readonly health?: HealthOptions<object> | Health<object>;
+    readonly logger?: Pick<Logger, 'error'>;
+    /** Echo `x-request-id` on every response. Defaults to true. */
+    readonly responseHeader?: boolean;
+}
+type Handler = (req: IncomingMessage, res: ServerResponse) => unknown;
+/**
+ * Wrap a handler with the request context, health routes and the error envelope. Anything the
+ * handler throws (or rejects with) is sent as an envelope; a handler that returns without
+ * responding gets a 404 envelope.
+ */
+export declare function hiveHandler(handler: Handler, options?: HiveHandlerOptions): RequestListener;
+export {};

package/dist/node-http/index.js

@@ -0,0 +1,91 @@
+import { createRequestContext, getRequestContext, runWithRequestContext, } from '../context/index.js';
+import { HiveError, toErrorResponse } from '../errors/index.js';
+import { createHealth } from '../health/index.js';
+import { OathweaveError } from '../oathweave/errors.js';
+/** The request context for `req`, created on first use and cached on the request. */
+const contexts = new WeakMap();
+export function requestContextFor(req, options = {}) {
+    let context = contexts.get(req);
+    if (!context) {
+        context = createRequestContext(req.headers, options);
+        contexts.set(req, context);
+    }
+    return context;
+}
+/** Verify the request's `Authorization: Bearer` header and record the principal on the context. */
+export async function authenticate(req, verifier, options = {}) {
+    const header = req.headers.authorization;
+    if (Array.isArray(header))
+        throw new OathweaveError('malformed_token');
+    const principal = await verifier.verifyAuthorization(header, options);
+    const context = contexts.get(req) ?? getRequestContext();
+    if (context)
+        context.principal = principal;
+    return principal;
+}
+/** Send a JSON body with `no-store` caching. */
+export function sendJson(res, status, body, headers = {}) {
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'content-length': Buffer.byteLength(payload),
+        ...headers,
+    });
+    res.end(res.req?.method === 'HEAD' ? undefined : payload);
+}
+/** Send any thrown value as the error envelope. Non-HiveErrors become a logged, generic 500. */
+export function sendError(res, error, options = {}) {
+    const response = toErrorResponse(error, {
+        requestId: options.requestId ?? getRequestContext()?.requestId,
+        onUnexpected: unexpected => options.logger?.error('unhandled error', { err: unexpected }),
+    });
+    sendJson(res, response.status, response.body, response.headers);
+}
+/**
+ * Serve a health path. Returns true when `req` was a health request and has been answered.
+ * The liveness body is the one `health` was created with (see `liveBody`).
+ */
+export async function handleHealth(req, res, health) {
+    if (req.method !== 'GET' && req.method !== 'HEAD')
+        return false;
+    const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+    const pending = health.handle(pathname);
+    if (!pending)
+        return false;
+    const result = await pending;
+    sendJson(res, result.status, result.body, result.headers);
+    return true;
+}
+function isHealth(value) {
+    return typeof value.handle === 'function';
+}
+/**
+ * Wrap a handler with the request context, health routes and the error envelope. Anything the
+ * handler throws (or rejects with) is sent as an envelope; a handler that returns without
+ * responding gets a 404 envelope.
+ */
+export function hiveHandler(handler, options = {}) {
+    const health = options.health ? (isHealth(options.health) ? options.health : createHealth(options.health)) : undefined;
+    return (req, res) => {
+        const context = requestContextFor(req, options);
+        if (options.responseHeader ?? true)
+            res.setHeader('x-request-id', context.requestId);
+        void runWithRequestContext(context, async () => {
+            try {
+                if (health && await handleHealth(req, res, health))
+                    return;
+                await handler(req, res);
+                if (!res.headersSent && !res.writableEnded)
+                    sendError(res, HiveError.notFound(), { requestId: context.requestId });
+            }
+            catch (error) {
+                sendError(res, error, { requestId: context.requestId, ...(options.logger ? { logger: options.logger } : {}) });
+            }
+        });
+    };
+}

package/dist/oathweave/claims.d.ts

@@ -0,0 +1,79 @@
+/** Pure claim checks and principal extraction for verified Oathweave access tokens. */
+import type { JWTPayload } from 'jose';
+export type PrincipalKind = 'user' | 'service';
+/** Which principals a verifier or route accepts. */
+export type AcceptPrincipal = PrincipalKind | 'any';
+interface PrincipalBase {
+    readonly kind: PrincipalKind;
+    readonly subject: string;
+    /** The issuer that signed this token (one of the configured issuers). */
+    readonly issuer: string;
+    readonly clientId: string;
+    /** The token's `jti`. */
+    readonly tokenId: string;
+    readonly roles: readonly string[];
+    readonly permissions: readonly string[];
+    /** From the space-separated `scope` claim (or an `scp` array). */
+    readonly scopes: readonly string[];
+    /** Epoch seconds. */
+    readonly issuedAt: number;
+    /** Epoch seconds. Streams must close by this time. */
+    readonly expiresAt: number;
+    /** All verified claims, for product-specific fields. */
+    readonly claims: Readonly<JWTPayload>;
+}
+/** A person, signed in through a client, with an Oathweave session. */
+export interface OathweaveUserPrincipal extends PrincipalBase {
+    readonly kind: 'user';
+    readonly sessionId: string;
+    /** From userinfo `name` when the session was checked online, else token `name`, `username` or the subject. */
+    readonly displayName: string;
+    /** When the person last proved their identity (epoch seconds). Undefined means unknown, never recent. */
+    readonly authTime: number | undefined;
+    /** True when the session was confirmed active against userinfo for this call. */
+    readonly sessionChecked: boolean;
+}
+/** A machine client (client_credentials): its subject is its client ID, and it has no session. */
+export interface OathweaveServicePrincipal extends PrincipalBase {
+    readonly kind: 'service';
+}
+export type OathweavePrincipal = OathweaveUserPrincipal | OathweaveServicePrincipal;
+/**
+ * Which claim names carry the client ID: Oathweave's `clientId`, RFC 9068 `client_id`, or
+ * `either` (the default).
+ */
+export type ClientIdClaim = 'clientId' | 'client_id' | 'either';
+export declare const CLIENT_ID_CLAIMS: readonly ClientIdClaim[];
+/**
+ * The client claim: Oathweave's `clientId`, or RFC 9068 `client_id`. Both present must agree,
+ * whichever name is accepted. With `clientId` or `client_id`, only that claim supplies the value.
+ */
+export declare function clientIdOf(payload: JWTPayload, claim?: ClientIdClaim): string | undefined;
+/** Scopes from `scope` (space-separated) or `scp` (array or string), de-duplicated. */
+export declare function extractScopes(payload: JWTPayload): string[];
+/**
+ * Roles; an absent claim is no roles, or invalid when `required` is true. A present claim that
+ * is not a string array is invalid.
+ */
+export declare function extractRoles(payload: JWTPayload, required?: boolean): string[] | undefined;
+/** A service token is one whose client ID equals its subject. */
+export declare function principalKindOf(payload: JWTPayload, claim?: ClientIdClaim): PrincipalKind;
+export interface ClaimPolicy {
+    readonly accept: AcceptPrincipal;
+    /** Largest allowed `exp - iat`, in seconds. */
+    readonly maxLifetimeSec: number;
+    /** Refuse a token without a `roles` claim. Defaults to false: an absent claim is no roles. */
+    readonly requireRoles?: boolean;
+    /** Which claim names supply the client ID. Defaults to `either`. */
+    readonly clientIdClaim?: ClientIdClaim;
+}
+/**
+ * Check the Oathweave claim rules on a payload whose signature, issuer, audience and time
+ * claims jose already verified, and build the principal (without session data).
+ *
+ * Users: `actorType` USER, a session, a client that is not the subject.
+ * Services: subject equals client ID, `actorType` SERVICE_ACCOUNT, `token_type` access, no session.
+ * Both: `jti`, string-array `permissions`, `exp - iat` within the lifetime limit.
+ */
+export declare function principalFromClaims(payload: JWTPayload, policy: ClaimPolicy): OathweavePrincipal;
+export {};

package/dist/oathweave/claims.js

@@ -0,0 +1,99 @@
+import { OathweaveError } from './errors.js';
+function stringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string');
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export const CLIENT_ID_CLAIMS = ['clientId', 'client_id', 'either'];
+/**
+ * The client claim: Oathweave's `clientId`, or RFC 9068 `client_id`. Both present must agree,
+ * whichever name is accepted. With `clientId` or `client_id`, only that claim supplies the value.
+ */
+export function clientIdOf(payload, claim = 'either') {
+    const camel = payload['clientId'];
+    const snake = payload['client_id'];
+    if (camel !== undefined && snake !== undefined && camel !== snake)
+        return undefined;
+    const value = claim === 'clientId' ? camel : claim === 'client_id' ? snake : camel ?? snake;
+    return typeof value === 'string' ? value : undefined;
+}
+/** Scopes from `scope` (space-separated) or `scp` (array or string), de-duplicated. */
+export function extractScopes(payload) {
+    const raw = payload['scope'] ?? payload['scp'];
+    const list = typeof raw === 'string' ? raw.split(/\s+/) : stringArray(raw) ? raw : [];
+    return [...new Set(list.map(item => item.trim()).filter(Boolean))];
+}
+/**
+ * Roles; an absent claim is no roles, or invalid when `required` is true. A present claim that
+ * is not a string array is invalid.
+ */
+export function extractRoles(payload, required = false) {
+    const roles = payload['roles'];
+    if (roles === undefined)
+        return required ? undefined : [];
+    return stringArray(roles) ? [...roles] : undefined;
+}
+/** A service token is one whose client ID equals its subject. */
+export function principalKindOf(payload, claim = 'either') {
+    const clientId = clientIdOf(payload, claim);
+    return clientId !== undefined && clientId === payload.sub ? 'service' : 'user';
+}
+function validAuthTime(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+/**
+ * Check the Oathweave claim rules on a payload whose signature, issuer, audience and time
+ * claims jose already verified, and build the principal (without session data).
+ *
+ * Users: `actorType` USER, a session, a client that is not the subject.
+ * Services: subject equals client ID, `actorType` SERVICE_ACCOUNT, `token_type` access, no session.
+ * Both: `jti`, string-array `permissions`, `exp - iat` within the lifetime limit.
+ */
+export function principalFromClaims(payload, policy) {
+    const { iat, exp, sub, jti, iss } = payload;
+    if (typeof iat !== 'number' || typeof exp !== 'number' || exp <= iat || exp - iat > policy.maxLifetimeSec) {
+        throw new OathweaveError('invalid_lifetime');
+    }
+    if (!nonEmpty(sub) || !nonEmpty(jti) || !nonEmpty(iss))
+        throw new OathweaveError('invalid_claims');
+    const permissions = payload['permissions'];
+    const clientIdClaim = policy.clientIdClaim ?? 'either';
+    const roles = extractRoles(payload, policy.requireRoles ?? false);
+    const clientId = clientIdOf(payload, clientIdClaim);
+    if (!stringArray(permissions) || roles === undefined || clientId === undefined)
+        throw new OathweaveError('invalid_claims');
+    const kind = principalKindOf(payload, clientIdClaim);
+    if (policy.accept !== 'any' && policy.accept !== kind)
+        throw new OathweaveError('wrong_principal_kind', { details: { kind } });
+    const base = {
+        subject: sub,
+        issuer: iss,
+        clientId,
+        tokenId: jti,
+        roles,
+        permissions: [...permissions],
+        scopes: extractScopes(payload),
+        issuedAt: iat,
+        expiresAt: exp,
+        claims: payload,
+    };
+    if (kind === 'service') {
+        if (payload['actorType'] !== 'SERVICE_ACCOUNT' || payload['token_type'] !== 'access' || payload['sessionId'] !== undefined) {
+            throw new OathweaveError('invalid_claims');
+        }
+        return { kind, ...base };
+    }
+    const sessionId = payload['sessionId'];
+    if (payload['actorType'] !== 'USER' || !nonEmpty(sessionId) || !nonEmpty(clientId))
+        throw new OathweaveError('invalid_claims');
+    const name = payload['name'] ?? payload['username'];
+    return {
+        kind,
+        ...base,
+        sessionId,
+        displayName: nonEmpty(name) ? name : sub,
+        authTime: validAuthTime(payload['auth_time']),
+        sessionChecked: false,
+    };
+}

package/dist/oathweave/conformance.d.ts

@@ -0,0 +1,88 @@
+import type { JSONWebKeySet } from 'jose';
+import type { PrincipalKind } from './claims.js';
+import type { OathweaveFailureReason } from './errors.js';
+export type ConformanceExpectation = {
+    readonly outcome: 'accept';
+    readonly kind: PrincipalKind;
+    readonly subject: string;
+    readonly clientId: string;
+    readonly roles: readonly string[];
+    readonly permissions: readonly string[];
+    readonly scopes: readonly string[];
+} | {
+    readonly outcome: 'reject';
+    readonly status: 401 | 403 | 503;
+    readonly reason: OathweaveFailureReason;
+};
+export interface ConformanceVector {
+    readonly name: string;
+    readonly description: string;
+    /** The principal kind the token claims to be, for products with separate user and service verifiers. */
+    readonly principal: PrincipalKind;
+    readonly token: string;
+    readonly expect: ConformanceExpectation;
+}
+export interface ConformanceVectors {
+    readonly schema: 1;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly jwksUrl: string;
+    readonly userinfoUrl: string;
+    /** The fixed evaluation time, RFC 3339. */
+    readonly now: string;
+    readonly jwks: JSONWebKeySet;
+    readonly vectors: readonly ConformanceVector[];
+}
+export interface ConformanceContext {
+    readonly issuer: string;
+    readonly audience: string;
+    readonly jwks: JSONWebKeySet;
+    readonly jwksUrl: string;
+    readonly userinfoUrl: string;
+    /** The fixed clock. Verifiers must evaluate time claims at this instant. */
+    readonly now: Date;
+    readonly nowMs: number;
+    readonly principal: PrincipalKind;
+    readonly vector: ConformanceVector;
+    /**
+     * A fetch that serves `jwksUrl` and `userinfoUrl` for the vectors, for verifiers that only
+     * take URLs. Userinfo answers with the bearer token's own subject, as an active session would.
+     */
+    readonly fetch: typeof fetch;
+}
+/** Verify `token` with the product's verifier. Resolve on acceptance, reject on refusal. */
+export type ConformanceVerify = (token: string, context: ConformanceContext) => Promise<unknown>;
+export interface ConformanceResult {
+    readonly name: string;
+    readonly passed: boolean;
+    readonly expected: ConformanceExpectation['outcome'];
+    readonly actual: 'accept' | 'reject';
+    /** Why a vector failed. */
+    readonly problem?: string;
+}
+export interface ConformanceReport {
+    readonly passed: number;
+    readonly failed: number;
+    readonly results: readonly ConformanceResult[];
+}
+export interface ConformanceOptions {
+    /** Use these vectors instead of the shipped file. */
+    readonly vectors?: ConformanceVectors;
+    /** Also require a matching `reason` on refusals (HiveCommon's OathweaveError has one). */
+    readonly strictReasons?: boolean;
+    /** Throw when any vector fails. Defaults to true, so a test fails with a readable message. */
+    readonly throwOnFailure?: boolean;
+    /** Run only vectors with these names. */
+    readonly only?: readonly string[];
+}
+/** Load the shipped vectors. */
+export declare function loadOathweaveVectors(): Promise<ConformanceVectors>;
+/**
+ * Run every vector through `verify` at the vectors' fixed clock. A vector expecting acceptance
+ * passes when `verify` resolves (and any `kind`, `subject`, `roles`, `permissions` or `scopes`
+ * on the result match); one expecting refusal passes when it rejects (and any numeric
+ * `status` on the error matches, plus `reason` with `strictReasons`).
+ */
+export declare function runOathweaveConformance(verify: ConformanceVerify, options?: ConformanceOptions): Promise<ConformanceReport>;
+/** A `ConformanceVerify` for this package's own verifier, for products that adopt it as is. */
+export declare function hiveCommonConformanceVerify(): ConformanceVerify;

package/dist/oathweave/conformance.js

@@ -0,0 +1,124 @@
+/**
+ * Oathweave verifier conformance. The package ships `test-vectors/oathweave/vectors.json`:
+ * a test JWKS and pre-signed tokens with expected outcomes, evaluated at a fixed clock so
+ * the vectors never rot. Each product runs them against its own verifier:
+ *
+ *   const report = await runOathweaveConformance((token, ctx) => myVerify(token, ctx));
+ */
+import { readFile } from 'node:fs/promises';
+import { createOathweaveVerifier } from './verifier.js';
+/** Load the shipped vectors. */
+export async function loadOathweaveVectors() {
+    const file = new URL('../../test-vectors/oathweave/vectors.json', import.meta.url);
+    return JSON.parse(await readFile(file, 'utf8'));
+}
+function decodePayload(token) {
+    const part = token.split('.')[1] ?? '';
+    return JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+}
+function vectorFetch(vectors) {
+    return async (input, init) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        if (url === vectors.jwksUrl)
+            return Response.json(vectors.jwks);
+        if (url === vectors.userinfoUrl) {
+            const header = new Headers(init?.headers).get('authorization') ?? '';
+            const token = /^Bearer (.+)$/.exec(header)?.[1];
+            if (!token)
+                return new Response('', { status: 401 });
+            const payload = decodePayload(token);
+            return Response.json({ sub: payload['sub'], name: 'Conformance User' });
+        }
+        return new Response('', { status: 404 });
+    };
+}
+function sameSet(a, b) {
+    return a.length === b.length && [...a].sort().join('\n') === [...b].sort().join('\n');
+}
+function checkAccepted(expect, value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const result = value;
+    // Only fields the verifier exposes are compared, so differently-shaped results still pass.
+    if (typeof result['kind'] === 'string' && result['kind'] !== expect.kind)
+        return `kind ${String(result['kind'])}, expected ${expect.kind}`;
+    if (typeof result['subject'] === 'string' && result['subject'] !== expect.subject)
+        return 'subject differs';
+    for (const field of ['roles', 'permissions', 'scopes']) {
+        const actual = result[field];
+        if (Array.isArray(actual) && !sameSet(actual, expect[field]))
+            return `${field} differ`;
+    }
+    return undefined;
+}
+function checkRejected(expect, error, strict) {
+    const record = error && typeof error === 'object' ? error : {};
+    const status = record['status'] ?? record['statusCode'];
+    if (typeof status === 'number' && status !== expect.status)
+        return `status ${status}, expected ${expect.status}`;
+    if (strict && record['reason'] !== expect.reason)
+        return `reason ${String(record['reason'])}, expected ${expect.reason}`;
+    return undefined;
+}
+/**
+ * Run every vector through `verify` at the vectors' fixed clock. A vector expecting acceptance
+ * passes when `verify` resolves (and any `kind`, `subject`, `roles`, `permissions` or `scopes`
+ * on the result match); one expecting refusal passes when it rejects (and any numeric
+ * `status` on the error matches, plus `reason` with `strictReasons`).
+ */
+export async function runOathweaveConformance(verify, options = {}) {
+    const vectors = options.vectors ?? await loadOathweaveVectors();
+    const fixed = new Date(vectors.now);
+    const fetcher = vectorFetch(vectors);
+    const results = [];
+    for (const vector of vectors.vectors) {
+        if (options.only && !options.only.includes(vector.name))
+            continue;
+        const context = {
+            issuer: vectors.issuer,
+            audience: vectors.audience,
+            jwks: vectors.jwks,
+            jwksUrl: vectors.jwksUrl,
+            userinfoUrl: vectors.userinfoUrl,
+            now: new Date(fixed),
+            nowMs: fixed.getTime(),
+            principal: vector.principal,
+            vector,
+            fetch: fetcher,
+        };
+        let actual;
+        let problem;
+        try {
+            const value = await verify(vector.token, context);
+            actual = 'accept';
+            if (vector.expect.outcome === 'accept')
+                problem = checkAccepted(vector.expect, value);
+            else
+                problem = `accepted a token that must be refused (${vector.expect.reason})`;
+        }
+        catch (error) {
+            actual = 'reject';
+            if (vector.expect.outcome === 'reject')
+                problem = checkRejected(vector.expect, error, options.strictReasons ?? false);
+            else
+                problem = `refused a valid token: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        results.push({ name: vector.name, passed: problem === undefined, expected: vector.expect.outcome, actual, ...(problem ? { problem } : {}) });
+    }
+    const failed = results.filter(result => !result.passed);
+    const report = { passed: results.length - failed.length, failed: failed.length, results };
+    if (failed.length && (options.throwOnFailure ?? true)) {
+        throw new Error(`Oathweave conformance failed for ${failed.length} of ${results.length} vectors:\n${failed.map(result => `- ${result.name}: ${result.problem}`).join('\n')}`);
+    }
+    return report;
+}
+/** A `ConformanceVerify` for this package's own verifier, for products that adopt it as is. */
+export function hiveCommonConformanceVerify() {
+    return (token, context) => createOathweaveVerifier({
+        issuer: context.issuer,
+        audience: context.audience,
+        keys: context.jwks,
+        now: () => context.nowMs,
+        accept: 'any',
+    }).verify(token);
+}

package/dist/oathweave/endpoint.d.ts

@@ -0,0 +1,15 @@
+/** Oathweave issuer and endpoint URL validation. */
+export interface EndpointOptions {
+    /**
+     * Allow `http:` for loopback hosts (`localhost`, `127.0.0.0/8`, `::1`). For tests and local
+     * development only; never enable it in production configuration.
+     */
+    readonly allowInsecureLoopback?: boolean;
+}
+export declare function isLoopbackHost(hostname: string): boolean;
+/** Why a URL is not an acceptable Oathweave endpoint, or undefined when it is. */
+export declare function endpointProblem(value: string, options?: EndpointOptions): string | undefined;
+/** Oathweave endpoints carry bearer tokens, so only verified HTTPS is acceptable. */
+export declare function isOathweaveEndpoint(value: string, options?: EndpointOptions): boolean;
+/** Throw a configuration error naming the setting when `value` is not an acceptable endpoint. */
+export declare function assertOathweaveEndpoint(value: string, name: string, options?: EndpointOptions): void;

package/dist/oathweave/endpoint.js

@@ -0,0 +1,35 @@
+/** Oathweave issuer and endpoint URL validation. */
+const LOOPBACK_V4 = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+export function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    return host === 'localhost' || host.endsWith('.localhost') || host === '::1' || LOOPBACK_V4.test(host);
+}
+/** Why a URL is not an acceptable Oathweave endpoint, or undefined when it is. */
+export function endpointProblem(value, options = {}) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'is not a valid URL';
+    }
+    if (url.username || url.password)
+        return 'must not contain credentials';
+    if (url.hash)
+        return 'must not contain a fragment';
+    if (url.protocol === 'https:')
+        return undefined;
+    if (url.protocol === 'http:' && options.allowInsecureLoopback && isLoopbackHost(url.hostname))
+        return undefined;
+    return url.protocol === 'http:' ? 'must use https (plain http is allowed only for loopback in tests)' : 'must use https';
+}
+/** Oathweave endpoints carry bearer tokens, so only verified HTTPS is acceptable. */
+export function isOathweaveEndpoint(value, options = {}) {
+    return endpointProblem(value, options) === undefined;
+}
+/** Throw a configuration error naming the setting when `value` is not an acceptable endpoint. */
+export function assertOathweaveEndpoint(value, name, options = {}) {
+    const problem = endpointProblem(value, options);
+    if (problem)
+        throw new TypeError(`Oathweave ${name} ${problem}`);
+}

package/dist/oathweave/errors.d.ts

@@ -0,0 +1,19 @@
+import { HiveError } from '../errors/index.js';
+/** Why a token or caller was refused. Stable: products and the conformance vectors rely on it. */
+export type OathweaveFailureReason = 'missing_token' | 'malformed_token' | 'algorithm_not_allowed' | 'unknown_key' | 'invalid_signature' | 'expired' | 'not_yet_valid' | 'invalid_issuer' | 'invalid_audience' | 'invalid_lifetime' | 'invalid_claims' | 'wrong_principal_kind' | 'session_inactive' | 'subject_mismatch' | 'not_linked' | 'insufficient_permission' | 'jwks_unavailable' | 'identity_unavailable';
+/** The HTTP status for a failure reason: 401, 403 or 503. */
+export declare function statusForReason(reason: OathweaveFailureReason): 401 | 403 | 503;
+/**
+ * A refused Oathweave credential. It is a HiveError, so error handlers send it as the suite
+ * envelope: `{ error: { code: 'invalid_token', message, details: { reason } } }` with 401, 403
+ * or 503. Messages are fixed per reason and never include the token or provider responses.
+ */
+export declare class OathweaveError extends HiveError {
+    readonly name = "OathweaveError";
+    readonly reason: OathweaveFailureReason;
+    constructor(reason: OathweaveFailureReason, options?: {
+        readonly cause?: unknown;
+        readonly details?: Record<string, unknown>;
+    });
+}
+export declare function isOathweaveError(value: unknown): value is OathweaveError;