@hivemagnus/hive-common 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ All notable changes to `@hivemagnus/hive-common` are recorded here. The format f
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-12
+
+Options that let a product keep its existing behaviour without wrapping the shared helpers. Every
+change is additive: the defaults are those of 0.1.0.
+
+### Added
+
+- `/oathweave`: `requireRoles` (default `false`) refuses a token without a `roles` array.
+- `/oathweave`: `clientIdClaim: 'clientId' | 'client_id' | 'either'` (default `'either'`) chooses
+  which claim names supply the client ID. Both claims present must still agree. `clientIdOf()`,
+  `principalKindOf()` and `extractRoles()` take matching optional arguments, and `ClaimPolicy`
+  matching optional fields. `CLIENT_ID_CLAIMS` and the `ClientIdClaim` type are exported.
+- `/oathweave`: `parseIdentityLinks()` accepts `localId` as an alias of `localUserId`. An entry
+  that sets both to different values is refused. Parsed links always use `localUserId`.
+- `/context`: `trustInboundRequestId` and `trustInboundTrace` trust the inbound request ID and the
+  inbound `traceparent`/`tracestate` separately. Each defaults to `trustInbound`. The `/hono` and
+  `/node-http` adapters take them too.
+- `/health`: `liveBody` replaces the `/health/live` body with a product's own, as an object or a
+  function of the standard body. `liveness()`, `createHealth()`, `Health`, `registerHealthRoutes()`
+  and `hiveHandler({ health })` accept it; `HealthOptions` and `Health` take an optional type
+  parameter for the body, defaulting to `LiveBody`.
+- README: "Choosing settings for an existing product".
+
 ## [0.1.0] - 2026-11-12
 
 First release: the shared server kit that replaces each product's own copy of the Oathweave
@@ -37,5 +60,6 @@ verifier and its own error, health and request-ID conventions.
   pagination and agent identity.
 - `/hono` and `/node-http` adapters for auth, request context, the error envelope and health.
 
-[Unreleased]: https://github.com/ChefTaco/HiveCommon/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ChefTaco/HiveCommon/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/ChefTaco/HiveCommon/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/ChefTaco/HiveCommon/releases/tag/v0.1.0

package/README.md

@@ -104,7 +104,8 @@ refetched, at most every 30 s, when a token names an unknown `kid`); `iss` is on
 
 - **User:** `actorType: "USER"`, a `sessionId`, a `clientId` other than the subject, string-array
   `permissions` and (optional) `roles`. With `userinfoUrl`, the session is confirmed online; the
-  answer is shared for 10 s from when the request started (failures for 2 s).
+  answer is shared for 10 s from when the request started (failures for 2 s), or not at all with
+  `sessionCacheTtlMs: 0`.
 - **Service:** `clientId` (or `client_id`) equals `sub`, `actorType: "SERVICE_ACCOUNT"`,
   `token_type: "access"`, no session.
 
@@ -129,6 +130,18 @@ const watch = watchStreamAuthorization({
 });
 ```
 
+Two options make the claim rules stricter for products that always required more:
+
+- `requireRoles: true` refuses a token without a `roles` array. The default (`false`) treats an
+  absent `roles` claim as no roles. A `roles` claim that is not a string array is always refused.
+- `clientIdClaim` chooses which claim names supply the client ID: `'clientId'` (Oathweave),
+  `'client_id'` (RFC 9068) or `'either'` (the default). When both claims are present they must
+  agree in every mode.
+
+Identity links name the local account `localUserId`. `localId`, the name older deployment configs
+use, is accepted as an alias; an entry that sets both to different values is refused. Parsed links
+always carry `localUserId`.
+
 Endpoints must be `https`. For tests against a loopback server, pass `allowInsecureLoopback: true`.
 
 ### Conformance vectors
@@ -205,6 +218,16 @@ A check is down when it throws, returns `false` or `{ ok: false }`, or exceeds i
 `signal` aborts). Error text is hidden unless `exposeErrors: true`. Serve legacy aliases only
 while old clients still call them.
 
+A product that has published its own liveness body can keep it with `liveBody`: an object served
+as is, or a function that receives the standard body on every request. Status, headers and
+readiness are unchanged, and liveness still never runs checks. `liveness()`, `createHealth()`,
+`registerHealthRoutes()` and `hiveHandler({ health })` all take it.
+
+```ts
+createHealth({ service: 'studio', liveBody: { status: 'ok' } });
+createHealth({ service: 'hive-skills', liveBody: standard => ({ status: 'ok', service: standard.service, protocol: 1 }) });
+```
+
 ### context
 
 ```ts
@@ -221,6 +244,12 @@ Also `parseTraceparent()`, `formatTraceparent()`, `generateTraceparent()`, `chil
 `readRequestId()`, `requireIdempotencyKey()` (428 when missing). On an edge service exposed to the
 internet, pass `trustInbound: false` so callers cannot choose IDs.
 
+`trustInboundRequestId` and `trustInboundTrace` decide the request ID and the trace separately; each
+defaults to `trustInbound` (itself `true`). An internet-facing service that should still join its
+callers' traces passes `{ trustInboundRequestId: false, trustInboundTrace: true }`. The `/hono`
+`requestContext()` middleware and the `/node-http` `hiveHandler()` and `requestContextFor()` take
+the same options.
+
 ### registry
 
 ```ts
@@ -366,6 +395,34 @@ Behaviour that changes when a product adopts the shared verifier:
 - Duplicate identity links fail at startup by default (`duplicates: 'ignore'` keeps the old
   Magnus behaviour of granting nothing to that identity).
 
+## Choosing settings for an existing product
+
+The defaults suit a new service. A product moving from its own code to HiveCommon can keep its
+existing behaviour with these settings instead of wrapping the shared helpers:
+
+| Setting | Default | Set it to keep |
+| --- | --- | --- |
+| `clockToleranceSec: 0` (verifier) | 30 | no clock skew allowance on `exp`, `nbf` and `iat` |
+| `sessionCacheTtlMs: 0` (verifier) | 10 000 | an online session check on every request, so sign-out is immediate |
+| `requireRoles: true` (verifier) | `false` | refusing tokens without a `roles` array |
+| `clientIdClaim: 'clientId'` (verifier) | `'either'` | requiring the Oathweave `clientId` claim; RFC 9068 `client_id` alone is refused |
+| `trustInboundRequestId: false` with `trustInboundTrace: true` (context, `/hono`, `/node-http`) | both `trustInbound` | generating every request ID on an internet-facing service while continuing callers' traces |
+| `liveBody` (health, `/hono`, `/node-http`) | the standard body | a published `/health/live` body such as `{ status: 'ok' }` |
+| `localId` in identity links | `localUserId` | existing link configs, unchanged |
+| `duplicates: 'ignore'` (identity links) | `'reject'` | granting nothing to a duplicated identity instead of failing at startup |
+
+```ts
+const verifier = createOathweaveVerifier({
+  issuer, audience: 'chattermost', jwksUrl, userinfoUrl,
+  clockToleranceSec: 0, sessionCacheTtlMs: 0, requireRoles: true, clientIdClaim: 'clientId',
+});
+app.use(requestContext({ trustInboundRequestId: false, trustInboundTrace: true }));
+registerHealthRoutes(app, { service: 'chattermost', liveBody: { status: 'ok' } });
+```
+
+Every refusal, including 503 `auth_unavailable`, is still an `OathweaveError`; a product that
+answers 401 for all of them maps the error in its own handler.
+
 ## Development
 
 ```bash

package/dist/context/index.d.ts

@@ -66,9 +66,21 @@ export interface RequestContext {
 export interface CreateRequestContextOptions {
     /**
      * Accept the inbound request ID and trace context. Defaults to true; set false on an edge
-     * service that must not let the public internet choose its IDs.
+     * service that must not let the public internet choose its IDs. The two settings below
+     * override it for one of the two.
      */
     readonly trustInbound?: boolean;
+    /**
+     * Accept an inbound `x-request-id` (or `x-hive-request-id`, `x-correlation-id`). Defaults to
+     * `trustInbound`. When false, every request gets a generated ID.
+     */
+    readonly trustInboundRequestId?: boolean;
+    /**
+     * Continue an inbound `traceparent` and `tracestate`. Defaults to `trustInbound`. When false,
+     * every request starts a new trace. An internet-facing service can set this true with
+     * `trustInboundRequestId: false` to join a caller's trace while choosing its own request IDs.
+     */
+    readonly trustInboundTrace?: boolean;
     readonly generateRequestId?: () => string;
     readonly now?: () => number;
 }

package/dist/context/index.js

@@ -147,8 +147,10 @@ export function requireIdempotencyKey(headers) {
 }
 export function createRequestContext(headers, options = {}) {
     const trust = options.trustInbound ?? true;
-    const requestId = (trust ? readRequestId(headers) : undefined) ?? (options.generateRequestId ?? generateRequestId)();
-    const parentTrace = trust ? parseTraceparent(readHeader(headers, HIVE_HEADERS.traceparent)) : undefined;
+    const trustRequestId = options.trustInboundRequestId ?? trust;
+    const trustTrace = options.trustInboundTrace ?? trust;
+    const requestId = (trustRequestId ? readRequestId(headers) : undefined) ?? (options.generateRequestId ?? generateRequestId)();
+    const parentTrace = trustTrace ? parseTraceparent(readHeader(headers, HIVE_HEADERS.traceparent)) : undefined;
     const rawState = parentTrace ? readHeader(headers, HIVE_HEADERS.tracestate)?.trim() : undefined;
     // eslint-disable-next-line no-control-regex
     const tracestate = rawState && rawState.length <= 512 && !/[\u0000-\u001f\u007f]/.test(rawState) ? rawState : undefined;

package/dist/health/index.d.ts

@@ -51,7 +51,13 @@ export interface HealthResponse<B> {
     readonly body: B;
     readonly headers: Readonly<Record<string, string>>;
 }
-export interface HealthOptions {
+/**
+ * A product's own liveness body, in place of the standard `LiveBody`: an object served as is,
+ * or a function called on every liveness request with the standard body.
+ */
+export type LiveBodyOverride<L extends object> = L | ((standard: LiveBody) => L);
+/** `L` is the liveness body type: `LiveBody` unless `liveBody` is set. */
+export interface HealthOptions<L extends object = LiveBody> {
     readonly service?: string;
     readonly version?: string;
     readonly checks?: readonly HealthCheck[];
@@ -65,21 +71,31 @@ export interface HealthOptions {
     /** Also serve the legacy paths in `LEGACY_HEALTH_ALIASES`, or a custom alias map. */
     readonly aliases?: boolean | Partial<Readonly<Record<HealthKind, readonly string[]>>>;
     readonly now?: () => number;
+    /**
+     * Serve this body from `/health/live` instead of the standard one, for a product that keeps
+     * a published liveness body such as `{ status: 'ok' }`. The status (200) and headers are
+     * unchanged, and liveness still never runs checks. Readiness is not affected.
+     */
+    readonly liveBody?: LiveBodyOverride<L>;
 }
-/** The liveness response: 200 whenever the process can answer. It never runs checks. */
-export declare function liveness(options?: HealthOptions): HealthResponse<LiveBody>;
+/**
+ * The liveness response: 200 whenever the process can answer. It never runs checks. The body
+ * is the standard `LiveBody`, or the product's own when `liveBody` is set.
+ */
+export declare function liveness<L extends object = LiveBody>(options?: HealthOptions<L>): HealthResponse<L>;
 /** Run every check concurrently and build the readiness response: 503 if a critical check is down. */
-export declare function readiness(options?: HealthOptions): Promise<HealthResponse<ReadyBody>>;
+export declare function readiness(options?: HealthOptions<object>): Promise<HealthResponse<ReadyBody>>;
 /** Which health endpoint a path names, including legacy aliases when enabled. */
 export declare function resolveHealthPath(pathname: string, aliases?: HealthOptions['aliases']): HealthKind | undefined;
 /** All paths served for each kind, standard first. */
 export declare function healthPaths(aliases?: HealthOptions['aliases']): Readonly<Record<HealthKind, readonly string[]>>;
-export interface Health {
-    live(): HealthResponse<LiveBody>;
+/** `L` is the liveness body type: `LiveBody` unless `liveBody` was set. */
+export interface Health<L extends object = LiveBody> {
+    live(): HealthResponse<L>;
     ready(): Promise<HealthResponse<ReadyBody>>;
     /** The response for a health path, or undefined when the path is not a health path. */
-    handle(pathname: string): Promise<HealthResponse<LiveBody | ReadyBody>> | undefined;
+    handle(pathname: string): Promise<HealthResponse<L | ReadyBody>> | undefined;
     readonly paths: Readonly<Record<HealthKind, readonly string[]>>;
 }
 /** Bind options once and serve both endpoints. */
-export declare function createHealth(options?: HealthOptions): Health;
+export declare function createHealth<L extends object = LiveBody>(options?: HealthOptions<L>): Health<L>;

package/dist/health/index.js

@@ -12,10 +12,22 @@ const HEADERS = { 'content-type': 'application/json; charset=utf-8', 'cache-cont
 function identity(options) {
     return { ...(options.service ? { service: options.service } : {}), ...(options.version ? { version: options.version } : {}) };
 }
-/** The liveness response: 200 whenever the process can answer. It never runs checks. */
+function assertLiveBody(value) {
+    if (value !== undefined && typeof value !== 'function' && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+        throw new TypeError('liveBody must be an object or a function');
+    }
+}
+/**
+ * The liveness response: 200 whenever the process can answer. It never runs checks. The body
+ * is the standard `LiveBody`, or the product's own when `liveBody` is set.
+ */
 export function liveness(options = {}) {
+    assertLiveBody(options.liveBody);
     const now = options.now ?? Date.now;
-    return { status: 200, body: { status: 'live', ...identity(options), time: new Date(now()).toISOString() }, headers: HEADERS };
+    const standard = { status: 'live', ...identity(options), time: new Date(now()).toISOString() };
+    const custom = options.liveBody;
+    const body = custom === undefined ? standard : typeof custom === 'function' ? custom(standard) : { ...custom };
+    return { status: 200, body: body, headers: HEADERS };
 }
 class CheckTimeout extends Error {
 }
@@ -97,6 +109,7 @@ function aliasMap(aliases) {
 }
 /** Bind options once and serve both endpoints. */
 export function createHealth(options = {}) {
+    assertLiveBody(options.liveBody);
     return {
         live: () => liveness(options),
         ready: () => readiness(options),

package/dist/hono/index.d.ts

@@ -11,7 +11,7 @@
  */
 import type { Context, Env, ErrorHandler, Hono, MiddlewareHandler, NotFoundHandler } from 'hono';
 import { type CreateRequestContextOptions, type RequestContext } from '../context/index.js';
-import { type HealthOptions } from '../health/index.js';
+import { type HealthOptions, type LiveBody } from '../health/index.js';
 import type { Logger } from '../log/index.js';
 import type { AcceptPrincipal, OathweavePrincipal } from '../oathweave/claims.js';
 import { type PermissionOptions } from '../oathweave/links.js';
@@ -60,5 +60,8 @@ export interface ErrorHandlerOptions {
 export declare function errorHandler(options?: ErrorHandlerOptions): ErrorHandler;
 /** `app.notFound(notFoundHandler())`: a 404 envelope. */
 export declare function notFoundHandler(): NotFoundHandler;
-/** Serve `/health/live`, `/health/ready` and any aliases on `app` (GET and HEAD). */
-export declare function registerHealthRoutes<E extends Env>(app: Hono<E>, options?: HealthOptions): void;
+/**
+ * Serve `/health/live`, `/health/ready` and any aliases on `app` (GET and HEAD). Set
+ * `liveBody` to keep a product's published liveness body.
+ */
+export declare function registerHealthRoutes<E extends Env, L extends object = LiveBody>(app: Hono<E>, options?: HealthOptions<L>): void;

package/dist/hono/index.js

@@ -91,7 +91,10 @@ export function errorHandler(options = {}) {
 export function notFoundHandler() {
     return c => respond(c, HiveError.notFound(), {});
 }
-/** Serve `/health/live`, `/health/ready` and any aliases on `app` (GET and HEAD). */
+/**
+ * Serve `/health/live`, `/health/ready` and any aliases on `app` (GET and HEAD). Set
+ * `liveBody` to keep a product's published liveness body.
+ */
 export function registerHealthRoutes(app, options = {}) {
     const health = createHealth(options);
     const serve = (kind) => async (c) => {

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

@@ -24,11 +24,14 @@ export interface SendErrorOptions {
 }
 /** 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>;
+/**
+ * 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 | Health;
+    readonly health?: HealthOptions<object> | Health<object>;
     readonly logger?: Pick<Logger, 'error'>;
     /** Echo `x-request-id` on every response. Defaults to true. */
     readonly responseHeader?: boolean;

package/dist/node-http/index.js

@@ -46,7 +46,10 @@ export function sendError(res, error, options = {}) {
     });
     sendJson(res, response.status, response.body, response.headers);
 }
-/** Serve a health path. Returns true when `req` was a health request and has been answered. */
+/**
+ * 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;

package/dist/oathweave/claims.d.ts

@@ -38,18 +38,34 @@ 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;
+/**
+ * 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. A present claim that is not a string array is invalid. */
-export declare function extractRoles(payload: JWTPayload): string[] | undefined;
+/**
+ * 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): PrincipalKind;
+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

package/dist/oathweave/claims.js

@@ -5,13 +5,17 @@ function stringArray(value) {
 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) {
+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 = camel ?? snake;
+    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. */
@@ -20,16 +24,19 @@ export function extractScopes(payload) {
     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) {
+/**
+ * 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 [];
+        return required ? undefined : [];
     return stringArray(roles) ? [...roles] : undefined;
 }
 /** A service token is one whose client ID equals its subject. */
-export function principalKindOf(payload) {
-    const clientId = clientIdOf(payload);
+export function principalKindOf(payload, claim = 'either') {
+    const clientId = clientIdOf(payload, claim);
     return clientId !== undefined && clientId === payload.sub ? 'service' : 'user';
 }
 function validAuthTime(value) {
@@ -51,11 +58,12 @@ export function principalFromClaims(payload, policy) {
     if (!nonEmpty(sub) || !nonEmpty(jti) || !nonEmpty(iss))
         throw new OathweaveError('invalid_claims');
     const permissions = payload['permissions'];
-    const roles = extractRoles(payload);
-    const clientId = clientIdOf(payload);
+    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);
+    const kind = principalKindOf(payload, clientIdClaim);
     if (policy.accept !== 'any' && policy.accept !== kind)
         throw new OathweaveError('wrong_principal_kind', { details: { kind } });
     const base = {

package/dist/oathweave/index.d.ts

@@ -3,7 +3,7 @@
  * 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 { CLIENT_ID_CLAIMS, clientIdOf, extractRoles, extractScopes, principalFromClaims, principalKindOf, type AcceptPrincipal, type ClaimPolicy, type ClientIdClaim, 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';

package/dist/oathweave/index.js

@@ -3,7 +3,7 @@
  * 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 { CLIENT_ID_CLAIMS, 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';

package/dist/oathweave/links.d.ts

@@ -33,6 +33,8 @@ export interface ParseIdentityLinksOptions {
 }
 /**
  * Parse a JSON array of links, for example from `<PRODUCT>_OATHWEAVE_IDENTITIES_JSON`.
+ * An entry may name its local account `localUserId` or, as older configs do, `localId`; an
+ * entry that sets both to different values is refused. Parsed links always use `localUserId`.
  * Throws an `IdentityLinkError` naming the first problem; the raw value is never echoed.
  */
 export declare function parseIdentityLinks(raw: string | unknown, options?: ParseIdentityLinksOptions): OathweaveIdentityLink[];

package/dist/oathweave/links.js

@@ -2,7 +2,8 @@ import { OathweaveError } from './errors.js';
 export class IdentityLinkError extends Error {
     name = 'IdentityLinkError';
 }
-const LINK_FIELDS = new Set(['issuer', 'subject', 'localUserId', 'role', 'displayName', 'permissions']);
+/** `localId` is accepted as an alias of `localUserId`, the name older deployment configs use. */
+const LINK_FIELDS = new Set(['issuer', 'subject', 'localUserId', 'localId', 'role', 'displayName', 'permissions']);
 function isHttpsUrl(value) {
     if (typeof value !== 'string')
         return false;
@@ -15,6 +16,8 @@ function isHttpsUrl(value) {
 }
 /**
  * Parse a JSON array of links, for example from `<PRODUCT>_OATHWEAVE_IDENTITIES_JSON`.
+ * An entry may name its local account `localUserId` or, as older configs do, `localId`; an
+ * entry that sets both to different values is refused. Parsed links always use `localUserId`.
  * Throws an `IdentityLinkError` naming the first problem; the raw value is never echoed.
  */
 export function parseIdentityLinks(raw, options = {}) {
@@ -40,7 +43,11 @@ export function parseIdentityLinks(raw, options = {}) {
         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;
+        const { issuer, subject, localId, role, displayName, permissions } = link;
+        if (link['localUserId'] !== undefined && localId !== undefined && link['localUserId'] !== localId) {
+            throw new IdentityLinkError(`${where}: localId and localUserId disagree`);
+        }
+        const localUserId = link['localUserId'] ?? localId;
         if (!isHttpsUrl(issuer))
             throw new IdentityLinkError(`${where}: issuer must be an https URL`);
         if (typeof subject !== 'string' || !subject || subject.length > 256)

package/dist/oathweave/verifier.d.ts

@@ -1,5 +1,5 @@
 import { type JSONWebKeySet, type JWTVerifyGetKey } from 'jose';
-import { type AcceptPrincipal, type OathweavePrincipal, type OathweaveServicePrincipal, type OathweaveUserPrincipal } from './claims.js';
+import { type AcceptPrincipal, type ClientIdClaim, 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;
@@ -42,8 +42,22 @@ export interface OathweaveVerifierOptions extends EndpointOptions {
     readonly jwksCacheMaxAgeMs?: number;
     /** Minimum time between refetches triggered by an unknown `kid` (key rotation). Defaults to 30 s. */
     readonly jwksCooldownMs?: number;
+    /**
+     * How long a userinfo answer is reused, in milliseconds. Defaults to 10 000; 0 checks the
+     * session online on every call.
+     */
     readonly sessionCacheTtlMs?: number;
     readonly sessionCacheMax?: number;
+    /**
+     * Refuse a token without a `roles` array. Defaults to false, where an absent `roles` claim
+     * means no roles. A present claim that is not a string array is always refused.
+     */
+    readonly requireRoles?: boolean;
+    /**
+     * Which claim names supply the client ID: `clientId` (Oathweave), `client_id` (RFC 9068) or
+     * `either` (the default). When both claims are present they must agree in every mode.
+     */
+    readonly clientIdClaim?: ClientIdClaim;
 }
 export interface VerifyOptions {
     /** Override the verifier's default `accept` for this call. */

package/dist/oathweave/verifier.js

@@ -7,7 +7,7 @@
  */
 import { createHash } from 'node:crypto';
 import { createLocalJWKSet, createRemoteJWKSet, customFetch, decodeProtectedHeader, errors as joseErrors, jwtVerify, } from 'jose';
-import { principalFromClaims, } from './claims.js';
+import { CLIENT_ID_CLAIMS, principalFromClaims, } from './claims.js';
 import { assertOathweaveEndpoint } from './endpoint.js';
 import { OathweaveError } from './errors.js';
 /** How long a userinfo answer is reused, measured from when its request started. */
@@ -110,6 +110,12 @@ export function createOathweaveVerifier(options) {
         throw new TypeError('clockToleranceSec must be 0-300');
     if (!(maxLifetimeSec > 0 && maxLifetimeSec <= 86_400))
         throw new TypeError('maxLifetimeSec must be 1-86400');
+    const requireRoles = options.requireRoles ?? false;
+    const clientIdClaim = options.clientIdClaim ?? 'either';
+    if (typeof requireRoles !== 'boolean')
+        throw new TypeError('requireRoles must be a boolean');
+    if (!CLIENT_ID_CLAIMS.includes(clientIdClaim))
+        throw new TypeError("clientIdClaim must be 'clientId', 'client_id' or 'either'");
     const defaultAccept = options.accept ?? 'user';
     const timeoutMs = options.requestTimeoutMs ?? OATHWEAVE_REQUEST_TIMEOUT_MS;
     const request = options.fetch ?? ((input, init) => fetch(input, init));
@@ -202,7 +208,12 @@ export function createOathweaveVerifier(options) {
         // jose accepts an audience array that contains ours; Oathweave issues exactly one audience.
         if (payload.aud !== options.audience)
             throw new OathweaveError('invalid_audience');
-        const principal = principalFromClaims(payload, { accept: verifyOptions.accept ?? defaultAccept, maxLifetimeSec });
+        const principal = principalFromClaims(payload, {
+            accept: verifyOptions.accept ?? defaultAccept,
+            maxLifetimeSec,
+            requireRoles,
+            clientIdClaim,
+        });
         if (principal.kind === 'user' && options.userinfoUrl) {
             const displayName = await sessionCheck(token, principal.subject);
             return { ...principal, displayName, sessionChecked: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/hive-common",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared server kit for the Hive:Magnus suite: Oathweave token verification, error envelope, health, request context, registry client, logging, events and framework adapters",
   "keywords": [
     "hive",