@hivemagnus/hive-common 0.0.0-stage → 0.1.0

package/dist/log/index.js

@@ -0,0 +1,80 @@
+/**
+ * A small structured JSON logger. One line per entry, secrets redacted, and the current
+ * request ID and trace ID added automatically from the request context.
+ */
+import { getRequestContext } from '../context/index.js';
+import { redact } from './redact.js';
+export { redact, redactHeaders, redactText, isSensitiveKey, REDACTED } from './redact.js';
+export const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const SEVERITY = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60, silent: 100 };
+function defaultLevel() {
+    const value = typeof process !== 'undefined' ? process.env['LOG_LEVEL']?.toLowerCase() : undefined;
+    return LOG_LEVELS.includes(value) ? value : 'info';
+}
+function serializeErrors(fields, stacks) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value instanceof Error) {
+            const code = value.code;
+            const status = value.status;
+            result[key] = {
+                name: value.name,
+                message: value.message,
+                ...(typeof code === 'string' || typeof code === 'number' ? { code } : {}),
+                ...(typeof status === 'number' ? { status } : {}),
+                ...(stacks && value.stack ? { stack: value.stack } : {}),
+            };
+        }
+        else
+            result[key] = value;
+    }
+    return result;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, (_key, item) => (typeof item === 'bigint' ? item.toString() : item));
+    }
+    catch {
+        return JSON.stringify({ level: 'error', msg: 'log entry could not be serialised' });
+    }
+}
+export function createLogger(options = {}) {
+    const level = options.level ?? defaultLevel();
+    const threshold = SEVERITY[level];
+    const write = options.write ?? ((line) => { process.stdout.write(`${line}\n`); });
+    const shouldRedact = options.redact ?? true;
+    const now = options.now ?? Date.now;
+    const context = options.context ?? getRequestContext;
+    const bindings = options.bindings ?? {};
+    const emit = (entryLevel, message, fields) => {
+        if (SEVERITY[entryLevel] < threshold)
+            return;
+        const current = context();
+        const merged = {
+            ...bindings,
+            ...(current ? current.bindings : {}),
+            ...serializeErrors({ ...fields }, options.stacks ?? false),
+        };
+        // Reserved fields win over bindings so a caller cannot forge them.
+        const entry = {
+            ...(shouldRedact ? redact(merged, { keys: options.redactKeys ?? [] }) : merged),
+            time: new Date(now()).toISOString(),
+            level: entryLevel,
+            msg: shouldRedact ? redact(message) : message,
+            ...(current ? { requestId: current.requestId, traceId: current.trace.traceId } : {}),
+        };
+        write(safeStringify(entry));
+    };
+    const logger = {
+        level,
+        trace: (message, fields) => emit('trace', message, fields),
+        debug: (message, fields) => emit('debug', message, fields),
+        info: (message, fields) => emit('info', message, fields),
+        warn: (message, fields) => emit('warn', message, fields),
+        error: (message, fields) => emit('error', message, fields),
+        fatal: (message, fields) => emit('fatal', message, fields),
+        child: childBindings => createLogger({ ...options, level, bindings: { ...bindings, ...childBindings } }),
+        isLevelEnabled: candidate => SEVERITY[candidate] >= threshold,
+    };
+    return logger;
+}

package/dist/log/redact.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Secret redaction for logs and diagnostics. Follows the suite pattern (secret-looking keys
+ * are masked, strings are scrubbed of credentials) and adds headers, JWTs, URL credentials,
+ * provider token formats and cycle-safe traversal.
+ */
+export declare const REDACTED = "[REDACTED]";
+/** True for a key whose value should never be logged. */
+export declare function isSensitiveKey(key: string): boolean;
+/** Scrub credentials out of free text. */
+export declare function redactText(value: string): string;
+export interface RedactOptions {
+    /** Extra keys to mask, compared case-insensitively and exactly. */
+    readonly keys?: readonly string[];
+}
+/**
+ * A deep copy of `value` with secrets masked. Sensitive keys holding strings, objects or
+ * arrays are replaced by `[REDACTED]`; numbers and booleans under such keys (token counts,
+ * `hasPassword` flags) are kept. Strings everywhere are scrubbed with `redactText()`.
+ * Errors become `{ name, message, code? }`; cycles become `[Circular]`.
+ */
+export declare function redact<T>(value: T, options?: RedactOptions): T;
+/** Mask sensitive request or response headers, keeping the others. */
+export declare function redactHeaders(headers: Readonly<Record<string, string | readonly string[] | undefined>> | Headers): Record<string, unknown>;

package/dist/log/redact.js

@@ -0,0 +1,111 @@
+/**
+ * Secret redaction for logs and diagnostics. Follows the suite pattern (secret-looking keys
+ * are masked, strings are scrubbed of credentials) and adds headers, JWTs, URL credentials,
+ * provider token formats and cycle-safe traversal.
+ */
+export const REDACTED = '[REDACTED]';
+const MAX_DEPTH = 10;
+/** Key fragments, compared after lowercasing and removing `-`, `_` and `.`. */
+const SENSITIVE_KEY_PARTS = [
+    'authorization', 'cookie', 'password', 'passwd', 'passphrase', 'secret', 'token',
+    'apikey', 'privatekey', 'accesskey', 'signingkey', 'credential', 'webhookurl', 'sessionid',
+];
+/** Keys that end in "key" but are not secret. */
+const NON_SECRET_KEYS = new Set(['publickey', 'idempotencykey', 'cachekey', 'sortkey', 'partitionkey', 'primarykey', 'foreignkey']);
+/** True for a key whose value should never be logged. */
+export function isSensitiveKey(key) {
+    const normalized = key.toLowerCase().replace(/[-_.\s]/g, '');
+    if (NON_SECRET_KEYS.has(normalized))
+        return false;
+    if (SENSITIVE_KEY_PARTS.some(part => normalized.includes(part)))
+        return true;
+    // key, apiKey, signing_key, x-api-key, keyMaterial...; not "keys", "monkey" is accepted collateral.
+    return normalized === 'key' || normalized.endsWith('key') || normalized.startsWith('keymaterial');
+}
+const TEXT_RULES = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, REDACTED],
+    // Authorization schemes.
+    [/\b(Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{4,}/gi, `$1 ${REDACTED}`],
+    // JWT / JWS compact serialisations (header.payload.signature, signature may be empty).
+    [/\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g, REDACTED],
+    // Provider key formats.
+    [/\bsk-[A-Za-z0-9_-]{12,}/g, REDACTED],
+    [/\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g, REDACTED],
+    [/\bnpm_[A-Za-z0-9]{20,}\b/g, REDACTED],
+    [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, REDACTED],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, REDACTED],
+    // Credentials in URLs.
+    [/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, `$1${REDACTED}@`],
+    // Secret-looking query parameters and key=value / key: value pairs.
+    [/([?&](?:access_token|refresh_token|id_token|token|code|client_secret|api_key|apikey|key|password|sig|signature)=)[^&#\s]+/gi, `$1${REDACTED}`],
+    [/\b((?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|client[_-]?secret|password|passwd|private[_-]?key)["']?\s*[:=]\s*["']?)[^"',\s}&]+/gi, `$1${REDACTED}`],
+];
+/** Scrub credentials out of free text. */
+export function redactText(value) {
+    let text = value;
+    for (const [pattern, replacement] of TEXT_RULES)
+        text = text.replace(pattern, replacement);
+    return text;
+}
+/**
+ * A deep copy of `value` with secrets masked. Sensitive keys holding strings, objects or
+ * arrays are replaced by `[REDACTED]`; numbers and booleans under such keys (token counts,
+ * `hasPassword` flags) are kept. Strings everywhere are scrubbed with `redactText()`.
+ * Errors become `{ name, message, code? }`; cycles become `[Circular]`.
+ */
+export function redact(value, options = {}) {
+    const extra = new Set((options.keys ?? []).map(key => key.toLowerCase()));
+    const seen = new WeakSet();
+    const visit = (item, depth) => {
+        if (typeof item === 'string')
+            return redactText(item);
+        if (typeof item === 'bigint')
+            return item.toString();
+        if (typeof item !== 'object' || item === null)
+            return item;
+        if (seen.has(item))
+            return '[Circular]';
+        if (depth >= MAX_DEPTH)
+            return '[Truncated]';
+        seen.add(item);
+        try {
+            if (item instanceof Date)
+                return Number.isNaN(item.getTime()) ? null : item.toISOString();
+            if (item instanceof Error) {
+                const code = item.code;
+                return { name: item.name, message: redactText(item.message), ...(typeof code === 'string' || typeof code === 'number' ? { code } : {}) };
+            }
+            if (typeof item.forEach === 'function' && typeof item.entries === 'function'
+                && typeof item.get === 'function' && !(item instanceof Map)) {
+                // fetch Headers and similar.
+                const record = {};
+                item.forEach((headerValue, key) => { record[key] = headerValue; });
+                return visit(record, depth);
+            }
+            if (item instanceof Map)
+                return visit(Object.fromEntries(item), depth);
+            if (item instanceof Set)
+                return visit([...item], depth);
+            if (ArrayBuffer.isView(item) || item instanceof ArrayBuffer)
+                return `[Binary ${item.byteLength} bytes]`;
+            if (Array.isArray(item))
+                return item.map(element => visit(element, depth + 1));
+            const result = {};
+            for (const [key, child] of Object.entries(item)) {
+                const sensitive = isSensitiveKey(key) || extra.has(key.toLowerCase());
+                result[key] = sensitive && (typeof child === 'string' || (typeof child === 'object' && child !== null))
+                    ? REDACTED
+                    : visit(child, depth + 1);
+            }
+            return result;
+        }
+        finally {
+            seen.delete(item);
+        }
+    };
+    return visit(value, 0);
+}
+/** Mask sensitive request or response headers, keeping the others. */
+export function redactHeaders(headers) {
+    return redact(headers);
+}

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

@@ -0,0 +1,43 @@
+/**
+ * `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. */
+export declare function handleHealth(req: IncomingMessage, res: ServerResponse, health: Health): Promise<boolean>;
+export interface HiveHandlerOptions extends CreateRequestContextOptions {
+    /** Serve health endpoints before `handler` runs. */
+    readonly health?: HealthOptions | Health;
+    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,88 @@
+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. */
+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,63 @@
+/** 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;
+/** The client claim: Oathweave's `clientId`, or RFC 9068 `client_id`. Both present must agree. */
+export declare function clientIdOf(payload: JWTPayload): 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. A present claim that is not a string array is invalid. */
+export declare function extractRoles(payload: JWTPayload): string[] | undefined;
+/** A service token is one whose client ID equals its subject. */
+export declare function principalKindOf(payload: JWTPayload): PrincipalKind;
+export interface ClaimPolicy {
+    readonly accept: AcceptPrincipal;
+    /** Largest allowed `exp - iat`, in seconds. */
+    readonly maxLifetimeSec: number;
+}
+/**
+ * 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,91 @@
+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;
+}
+/** The client claim: Oathweave's `clientId`, or RFC 9068 `client_id`. Both present must agree. */
+export function clientIdOf(payload) {
+    const camel = payload['clientId'];
+    const snake = payload['client_id'];
+    if (camel !== undefined && snake !== undefined && camel !== snake)
+        return undefined;
+    const value = 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. A present claim that is not a string array is invalid. */
+export function extractRoles(payload) {
+    const roles = payload['roles'];
+    if (roles === undefined)
+        return [];
+    return stringArray(roles) ? [...roles] : undefined;
+}
+/** A service token is one whose client ID equals its subject. */
+export function principalKindOf(payload) {
+    const clientId = clientIdOf(payload);
+    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 roles = extractRoles(payload);
+    const clientId = clientIdOf(payload);
+    if (!stringArray(permissions) || roles === undefined || clientId === undefined)
+        throw new OathweaveError('invalid_claims');
+    const kind = principalKindOf(payload);
+    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;