@hivemagnus/hive-common 0.0.0-stage → 0.1.0

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;

package/dist/oathweave/errors.js

@@ -0,0 +1,70 @@
+import { HiveError } from '../errors/index.js';
+const MESSAGES = {
+    missing_token: 'A bearer token is required',
+    malformed_token: 'The bearer token is malformed',
+    algorithm_not_allowed: 'The token signing algorithm is not allowed',
+    unknown_key: 'The token was signed by an unknown key',
+    invalid_signature: 'The token signature is not valid',
+    expired: 'The token has expired',
+    not_yet_valid: 'The token is not valid yet',
+    invalid_issuer: 'The token issuer is not accepted',
+    invalid_audience: 'The token is not for this service',
+    invalid_lifetime: 'The token lifetime is not acceptable',
+    invalid_claims: 'The token claims are not valid',
+    wrong_principal_kind: 'This kind of caller is not accepted here',
+    session_inactive: 'The identity session is no longer active',
+    subject_mismatch: 'The identity session does not match the token',
+    not_linked: 'This identity has no access to this service',
+    insufficient_permission: 'The caller lacks a required permission',
+    jwks_unavailable: 'The identity provider keys are unavailable',
+    identity_unavailable: 'The identity provider is unavailable',
+};
+/** The HTTP status for a failure reason: 401, 403 or 503. */
+export function statusForReason(reason) {
+    if (reason === 'not_linked' || reason === 'insufficient_permission')
+        return 403;
+    if (reason === 'jwks_unavailable' || reason === 'identity_unavailable')
+        return 503;
+    return 401;
+}
+function codeForReason(reason) {
+    const status = statusForReason(reason);
+    if (status === 403)
+        return reason === 'insufficient_permission' ? 'insufficient_permission' : 'forbidden';
+    if (status === 503)
+        return 'auth_unavailable';
+    return reason === 'missing_token' ? 'unauthorized' : 'invalid_token';
+}
+function challenge(reason) {
+    const status = statusForReason(reason);
+    if (status === 401)
+        return { 'www-authenticate': reason === 'missing_token' ? 'Bearer' : 'Bearer error="invalid_token"' };
+    if (reason === 'insufficient_permission')
+        return { 'www-authenticate': 'Bearer error="insufficient_scope"' };
+    if (status === 503)
+        return { 'retry-after': '1' };
+    return undefined;
+}
+/**
+ * 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 class OathweaveError extends HiveError {
+    name = 'OathweaveError';
+    reason;
+    constructor(reason, options = {}) {
+        const headers = challenge(reason);
+        super(codeForReason(reason), MESSAGES[reason], {
+            status: statusForReason(reason),
+            details: { reason, ...options.details },
+            ...(headers ? { headers } : {}),
+            ...(options.cause !== undefined ? { cause: options.cause } : {}),
+        });
+        this.reason = reason;
+    }
+}
+export function isOathweaveError(value) {
+    return value instanceof OathweaveError
+        || (HiveError.is(value) && typeof value.reason === 'string' && value.name === 'OathweaveError');
+}

package/dist/oathweave/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@hivemagnus/hive-common/oathweave`: Oathweave access-token verification for suite services.
+ * Framework-free; see `/hono` and `/node-http` for middleware.
+ */
+export { createOathweaveVerifier, parseBearerToken, OATHWEAVE_DEFAULT_CLOCK_TOLERANCE_SEC, OATHWEAVE_FAILED_CHECK_TTL_MS, OATHWEAVE_MAX_LIFETIME_SEC, OATHWEAVE_MAX_TOKEN_LENGTH, OATHWEAVE_REQUEST_TIMEOUT_MS, OATHWEAVE_SESSION_CACHE_MAX, OATHWEAVE_SESSION_CACHE_TTL_MS, OATHWEAVE_STREAM_RECHECK_MS, type OathweaveVerifier, type OathweaveVerifierOptions, type VerifyOptions, } from './verifier.js';
+export { clientIdOf, extractRoles, extractScopes, principalFromClaims, principalKindOf, type AcceptPrincipal, type ClaimPolicy, type OathweavePrincipal, type OathweaveServicePrincipal, type OathweaveUserPrincipal, type PrincipalKind, } from './claims.js';
+export { OathweaveError, isOathweaveError, statusForReason, type OathweaveFailureReason } from './errors.js';
+export { assertOathweaveEndpoint, endpointProblem, isLoopbackHost, isOathweaveEndpoint, type EndpointOptions } from './endpoint.js';
+export { effectivePermissions, hasAnyRole, hasPermissions, hasScopes, IdentityLinkError, parseIdentityLinks, permissionMatches, requireIdentityLink, requirePermissions, uniqueIdentityLink, type OathweaveIdentityLink, type ParseIdentityLinksOptions, type PermissionOptions, } from './links.js';
+export { watchStreamAuthorization, type StreamWatch, type StreamWatchOptions } from './stream.js';

package/dist/oathweave/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@hivemagnus/hive-common/oathweave`: Oathweave access-token verification for suite services.
+ * Framework-free; see `/hono` and `/node-http` for middleware.
+ */
+export { createOathweaveVerifier, parseBearerToken, OATHWEAVE_DEFAULT_CLOCK_TOLERANCE_SEC, OATHWEAVE_FAILED_CHECK_TTL_MS, OATHWEAVE_MAX_LIFETIME_SEC, OATHWEAVE_MAX_TOKEN_LENGTH, OATHWEAVE_REQUEST_TIMEOUT_MS, OATHWEAVE_SESSION_CACHE_MAX, OATHWEAVE_SESSION_CACHE_TTL_MS, OATHWEAVE_STREAM_RECHECK_MS, } from './verifier.js';
+export { clientIdOf, extractRoles, extractScopes, principalFromClaims, principalKindOf, } from './claims.js';
+export { OathweaveError, isOathweaveError, statusForReason } from './errors.js';
+export { assertOathweaveEndpoint, endpointProblem, isLoopbackHost, isOathweaveEndpoint } from './endpoint.js';
+export { effectivePermissions, hasAnyRole, hasPermissions, hasScopes, IdentityLinkError, parseIdentityLinks, permissionMatches, requireIdentityLink, requirePermissions, uniqueIdentityLink, } from './links.js';
+export { watchStreamAuthorization } from './stream.js';

package/dist/oathweave/links.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Identity links and authorization helpers.
+ *
+ * A link maps one verified Oathweave identity (issuer + subject) to a local account. Products
+ * refuse identities without exactly one link, so a valid token alone never grants access.
+ */
+import type { OathweavePrincipal } from './claims.js';
+export interface OathweaveIdentityLink {
+    readonly issuer: string;
+    readonly subject: string;
+    /** The local account this identity acts as. Never `system` or a `service:` actor. */
+    readonly localUserId: string;
+    /** A role ceiling, when the product uses roles. */
+    readonly role?: string;
+    readonly displayName?: string;
+    /** A permission ceiling: the token's permissions grant only within it. Absent means no ceiling. */
+    readonly permissions?: readonly string[];
+}
+export declare class IdentityLinkError extends Error {
+    readonly name = "IdentityLinkError";
+}
+export interface ParseIdentityLinksOptions {
+    /** Allowed `role` values. When set, every link must carry one of them. */
+    readonly roles?: readonly string[];
+    /** Allowed `permissions` entries. When set, every listed permission must be one of them. */
+    readonly permissions?: readonly string[];
+    /**
+     * `reject` (default) fails on two links for the same identity. `ignore` keeps them, and
+     * `uniqueIdentityLink()` then grants nothing for that identity.
+     */
+    readonly duplicates?: 'reject' | 'ignore';
+    readonly maxLinks?: number;
+}
+/**
+ * Parse a JSON array of links, for example from `<PRODUCT>_OATHWEAVE_IDENTITIES_JSON`.
+ * Throws an `IdentityLinkError` naming the first problem; the raw value is never echoed.
+ */
+export declare function parseIdentityLinks(raw: string | unknown, options?: ParseIdentityLinksOptions): OathweaveIdentityLink[];
+/** The one link for a verified identity. A missing or duplicated link yields nothing. */
+export declare function uniqueIdentityLink<L extends OathweaveIdentityLink>(links: readonly L[], issuer: string, subject: string): L | undefined;
+/** The link for a principal, or a 403 `not_linked` OathweaveError. */
+export declare function requireIdentityLink<L extends OathweaveIdentityLink>(links: readonly L[], principal: Pick<OathweavePrincipal, 'issuer' | 'subject'>): L;
+/**
+ * Does one granted permission cover a required one? Exact match, `*`, or a `*` segment
+ * (split on `:`) covering the rest: `iam:*` covers `iam:users:read`.
+ */
+export declare function permissionMatches(granted: string, required: string): boolean;
+export interface PermissionOptions {
+    /** Honour `*` wildcards in granted permissions. Defaults to true, as the Oathweave SDK does. */
+    readonly wildcards?: boolean;
+}
+/** True when `granted` covers every one of `required`. */
+export declare function hasPermissions(granted: readonly string[], required: readonly string[], options?: PermissionOptions): boolean;
+/** Throw a 403 `insufficient_permission` OathweaveError unless the principal has every permission. */
+export declare function requirePermissions(principal: Pick<OathweavePrincipal, 'permissions'>, required: readonly string[], options?: PermissionOptions): void;
+/** True when the principal has at least one of `roles`. */
+export declare function hasAnyRole(principal: Pick<OathweavePrincipal, 'roles'>, roles: readonly string[]): boolean;
+/** True when the principal has every one of `scopes`. */
+export declare function hasScopes(principal: Pick<OathweavePrincipal, 'scopes'>, scopes: readonly string[]): boolean;
+/** Token permissions narrowed by a link's ceiling (and optionally a product's known set). */
+export declare function effectivePermissions(link: Pick<OathweaveIdentityLink, 'permissions'>, tokenPermissions: readonly string[], known?: readonly string[]): string[];

package/dist/oathweave/links.js

@@ -0,0 +1,131 @@
+import { OathweaveError } from './errors.js';
+export class IdentityLinkError extends Error {
+    name = 'IdentityLinkError';
+}
+const LINK_FIELDS = new Set(['issuer', 'subject', 'localUserId', 'role', 'displayName', 'permissions']);
+function isHttpsUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        return new URL(value).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse a JSON array of links, for example from `<PRODUCT>_OATHWEAVE_IDENTITIES_JSON`.
+ * Throws an `IdentityLinkError` naming the first problem; the raw value is never echoed.
+ */
+export function parseIdentityLinks(raw, options = {}) {
+    let json = raw;
+    if (typeof raw === 'string') {
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            throw new IdentityLinkError('identity links must be valid JSON');
+        }
+    }
+    if (!Array.isArray(json))
+        throw new IdentityLinkError('identity links must be a JSON array');
+    if (json.length > (options.maxLinks ?? 10_000))
+        throw new IdentityLinkError('too many identity links');
+    const seen = new Set();
+    return json.map((item, index) => {
+        const where = `identity link ${index}`;
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new IdentityLinkError(`${where} must be an object`);
+        const link = item;
+        for (const key of Object.keys(link))
+            if (!LINK_FIELDS.has(key))
+                throw new IdentityLinkError(`${where} has unknown field ${key.slice(0, 40)}`);
+        const { issuer, subject, localUserId, role, displayName, permissions } = link;
+        if (!isHttpsUrl(issuer))
+            throw new IdentityLinkError(`${where}: issuer must be an https URL`);
+        if (typeof subject !== 'string' || !subject || subject.length > 256)
+            throw new IdentityLinkError(`${where}: subject must be 1-256 characters`);
+        if (typeof localUserId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._@:-]{0,255}$/.test(localUserId)) {
+            throw new IdentityLinkError(`${where}: localUserId is not valid`);
+        }
+        // These identifiers name server-owned actors; a link must never impersonate one.
+        if (localUserId === 'system' || localUserId.startsWith('service:')) {
+            throw new IdentityLinkError(`${where}: localUserId must not name the system or a service actor`);
+        }
+        if (options.roles ? typeof role !== 'string' || !options.roles.includes(role) : role !== undefined && (typeof role !== 'string' || !role)) {
+            throw new IdentityLinkError(`${where}: role is not allowed`);
+        }
+        if (displayName !== undefined && (typeof displayName !== 'string' || !displayName.trim() || displayName.length > 120)) {
+            throw new IdentityLinkError(`${where}: displayName must be 1-120 characters`);
+        }
+        if (permissions !== undefined && (!Array.isArray(permissions) || !permissions.every(value => typeof value === 'string'
+            && (!options.permissions || options.permissions.includes(value))))) {
+            throw new IdentityLinkError(`${where}: permissions are not valid`);
+        }
+        const key = JSON.stringify([issuer, subject]);
+        if (seen.has(key) && (options.duplicates ?? 'reject') === 'reject')
+            throw new IdentityLinkError(`${where} duplicates an earlier link`);
+        seen.add(key);
+        return {
+            issuer,
+            subject,
+            localUserId,
+            ...(typeof role === 'string' ? { role } : {}),
+            ...(typeof displayName === 'string' ? { displayName: displayName.trim() } : {}),
+            ...(Array.isArray(permissions) ? { permissions: [...permissions] } : {}),
+        };
+    });
+}
+/** The one link for a verified identity. A missing or duplicated link yields nothing. */
+export function uniqueIdentityLink(links, issuer, subject) {
+    const matches = links.filter(link => link.issuer === issuer && link.subject === subject);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/** The link for a principal, or a 403 `not_linked` OathweaveError. */
+export function requireIdentityLink(links, principal) {
+    const link = uniqueIdentityLink(links, principal.issuer, principal.subject);
+    if (!link)
+        throw new OathweaveError('not_linked');
+    return link;
+}
+/**
+ * Does one granted permission cover a required one? Exact match, `*`, or a `*` segment
+ * (split on `:`) covering the rest: `iam:*` covers `iam:users:read`.
+ */
+export function permissionMatches(granted, required) {
+    if (granted === '*' || granted === required)
+        return true;
+    const grantedParts = granted.split(':');
+    const requiredParts = required.split(':');
+    for (let index = 0; index < grantedParts.length; index++) {
+        if (grantedParts[index] === '*')
+            return index < requiredParts.length;
+        if (grantedParts[index] !== requiredParts[index])
+            return false;
+    }
+    return grantedParts.length === requiredParts.length;
+}
+/** True when `granted` covers every one of `required`. */
+export function hasPermissions(granted, required, options = {}) {
+    const wildcards = options.wildcards ?? true;
+    return required.every(need => granted.some(have => (wildcards ? permissionMatches(have, need) : have === need)));
+}
+/** Throw a 403 `insufficient_permission` OathweaveError unless the principal has every permission. */
+export function requirePermissions(principal, required, options = {}) {
+    if (!hasPermissions(principal.permissions, required, options)) {
+        throw new OathweaveError('insufficient_permission', { details: { required: [...required] } });
+    }
+}
+/** True when the principal has at least one of `roles`. */
+export function hasAnyRole(principal, roles) {
+    return roles.some(role => principal.roles.includes(role));
+}
+/** True when the principal has every one of `scopes`. */
+export function hasScopes(principal, scopes) {
+    return scopes.every(scope => principal.scopes.includes(scope));
+}
+/** Token permissions narrowed by a link's ceiling (and optionally a product's known set). */
+export function effectivePermissions(link, tokenPermissions, known) {
+    const ceiling = link.permissions ? new Set(link.permissions) : undefined;
+    return [...new Set(tokenPermissions)].filter(permission => (!ceiling || ceiling.has(permission)) && (!known || known.includes(permission)));
+}

package/dist/oathweave/stream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Re-checking authorization on long-lived connections (SSE, WebSocket, long poll).
+ *
+ * A stream verified once at open would outlive a sign-out. `watchStreamAuthorization()`
+ * re-verifies every `OATHWEAVE_STREAM_RECHECK_MS` (the verifier's 10 s session cache keeps
+ * that cheap) and ends the stream at the token's expiry, so sign-out takes effect within
+ * about 15 seconds on open streams as well as on ordinary requests.
+ */
+import { OathweaveError } from './errors.js';
+export interface StreamWatchOptions {
+    /** Re-verify the caller. Usually `() => verifier.verify(token)`. Rejecting ends the stream. */
+    readonly recheck: () => Promise<{
+        readonly expiresAt: number;
+    }>;
+    /** Token expiry in epoch seconds. The stream ends then even if rechecks pass. */
+    readonly expiresAt: number;
+    /** Called once when the stream must close. */
+    readonly onEnd: (error: OathweaveError) => void;
+    readonly intervalMs?: number;
+    readonly now?: () => number;
+}
+export interface StreamWatch {
+    stop(): void;
+    readonly stopped: boolean;
+}
+export declare function watchStreamAuthorization(options: StreamWatchOptions): StreamWatch;

package/dist/oathweave/stream.js

@@ -0,0 +1,46 @@
+/**
+ * Re-checking authorization on long-lived connections (SSE, WebSocket, long poll).
+ *
+ * A stream verified once at open would outlive a sign-out. `watchStreamAuthorization()`
+ * re-verifies every `OATHWEAVE_STREAM_RECHECK_MS` (the verifier's 10 s session cache keeps
+ * that cheap) and ends the stream at the token's expiry, so sign-out takes effect within
+ * about 15 seconds on open streams as well as on ordinary requests.
+ */
+import { OathweaveError } from './errors.js';
+import { OATHWEAVE_STREAM_RECHECK_MS } from './verifier.js';
+export function watchStreamAuthorization(options) {
+    const now = options.now ?? Date.now;
+    const intervalMs = options.intervalMs ?? OATHWEAVE_STREAM_RECHECK_MS;
+    let stopped = false;
+    let inFlight = false;
+    const end = (error) => {
+        if (stopped)
+            return;
+        stop();
+        options.onEnd(error);
+    };
+    const expiryDelay = Math.max(0, options.expiresAt * 1000 - now());
+    // setTimeout cannot hold more than ~24.8 days; tokens never live that long.
+    const expiryTimer = setTimeout(() => end(new OathweaveError('expired')), Math.min(expiryDelay, 2_147_483_647));
+    const interval = setInterval(() => {
+        if (inFlight || stopped)
+            return;
+        inFlight = true;
+        options.recheck().then(() => { inFlight = false; }, (error) => {
+            inFlight = false;
+            end(error instanceof OathweaveError ? error : new OathweaveError('session_inactive', { cause: error }));
+        });
+    }, intervalMs);
+    // Never keep a process alive just to watch a stream.
+    expiryTimer.unref?.();
+    interval.unref?.();
+    function stop() {
+        stopped = true;
+        clearTimeout(expiryTimer);
+        clearInterval(interval);
+    }
+    return {
+        stop,
+        get stopped() { return stopped; },
+    };
+}

package/dist/oathweave/verifier.d.ts

@@ -0,0 +1,69 @@
+import { type JSONWebKeySet, type JWTVerifyGetKey } from 'jose';
+import { type AcceptPrincipal, type OathweavePrincipal, type OathweaveServicePrincipal, type OathweaveUserPrincipal } from './claims.js';
+import { type EndpointOptions } from './endpoint.js';
+/** How long a userinfo answer is reused, measured from when its request started. */
+export declare const OATHWEAVE_SESSION_CACHE_TTL_MS = 10000;
+/** How often a long-lived connection should re-check its token. */
+export declare const OATHWEAVE_STREAM_RECHECK_MS = 5000;
+/** Failed session checks are remembered this long, so one failing request does not verify twice. */
+export declare const OATHWEAVE_FAILED_CHECK_TTL_MS = 2000;
+export declare const OATHWEAVE_SESSION_CACHE_MAX = 5000;
+export declare const OATHWEAVE_REQUEST_TIMEOUT_MS = 3000;
+/** Oathweave access tokens live at most fifteen minutes. */
+export declare const OATHWEAVE_MAX_LIFETIME_SEC = 900;
+export declare const OATHWEAVE_DEFAULT_CLOCK_TOLERANCE_SEC = 30;
+/** Longest accepted compact token. Real Oathweave tokens are well under 4 KiB. */
+export declare const OATHWEAVE_MAX_TOKEN_LENGTH = 16384;
+export interface OathweaveVerifierOptions extends EndpointOptions {
+    /** Accepted issuer, or issuers. Each must be an https URL. */
+    readonly issuer: string | readonly string[];
+    /** This service's resource audience, for example `hivemem`. Matched exactly. */
+    readonly audience: string;
+    /** The issuer's JWKS endpoint. Required unless `keys` is given. */
+    readonly jwksUrl?: string;
+    /**
+     * The userinfo endpoint. When set, user tokens are also checked online, so a signed-out
+     * session stops working within the cache TTL. Recommended for every product.
+     */
+    readonly userinfoUrl?: string;
+    /** A local JWKS or a jose key resolver, instead of fetching `jwksUrl`. */
+    readonly keys?: JSONWebKeySet | JWTVerifyGetKey;
+    /** Which principals `verify()` accepts by default. Defaults to `user`. */
+    readonly accept?: AcceptPrincipal;
+    /** Seconds of clock skew tolerated on `exp`, `nbf` and `iat`. Defaults to 30. */
+    readonly clockToleranceSec?: number;
+    /** Largest `exp - iat` and token age in seconds. Defaults to 900. */
+    readonly maxLifetimeSec?: number;
+    readonly fetch?: typeof fetch;
+    /** Clock in epoch milliseconds. */
+    readonly now?: () => number;
+    readonly requestTimeoutMs?: number;
+    /** How long fetched keys are trusted before a refetch. Defaults to 10 minutes. */
+    readonly jwksCacheMaxAgeMs?: number;
+    /** Minimum time between refetches triggered by an unknown `kid` (key rotation). Defaults to 30 s. */
+    readonly jwksCooldownMs?: number;
+    readonly sessionCacheTtlMs?: number;
+    readonly sessionCacheMax?: number;
+}
+export interface VerifyOptions {
+    /** Override the verifier's default `accept` for this call. */
+    readonly accept?: AcceptPrincipal;
+}
+export interface OathweaveVerifier {
+    readonly issuers: readonly string[];
+    readonly audience: string;
+    verify(token: string, options?: VerifyOptions): Promise<OathweavePrincipal>;
+    verifyUser(token: string): Promise<OathweaveUserPrincipal>;
+    verifyService(token: string): Promise<OathweaveServicePrincipal>;
+    /** Verify an `Authorization` header value. A missing header is `missing_token`. */
+    verifyAuthorization(header: string | null | undefined, options?: VerifyOptions): Promise<OathweavePrincipal>;
+    /** Forget cached session answers, for example after a sign-out event. */
+    clearSessionCache(): void;
+}
+/**
+ * The token in an `Authorization: Bearer` header (RFC 6750). Undefined when there is no
+ * header; throws `malformed_token` when there is one but it is not a single bearer token.
+ */
+export declare function parseBearerToken(header: string | null | undefined): string | undefined;
+/** Create a verifier. Throws a TypeError at startup when the configuration is unsafe. */
+export declare function createOathweaveVerifier(options: OathweaveVerifierOptions): OathweaveVerifier;