@request-seal/core 0.1.0 → 0.3.0

package/dist/errors/parity.js

@@ -1,5 +1,6 @@
-// Derived from pinned Elixir constructors and call sites; regenerate with scripts/render-parity.ts --update-table.
-export const ELIXIR_ERROR_PIN = 'b2392871933d99641a7cb2ca2726aefd20081dee';
+// Derived from pinned Elixir constructors and call sites; regenerate with scripts/generate-parity.ts or scripts/render-parity.ts --update-table.
+/** The immutable reference release used for the error vocabulary. */
+export const ELIXIR_ERROR_PIN = '53b6690ccd5036d58b280d08cf0cacc6427262fe';
 const entries = [
     {
         "kind": "core",
@@ -253,6 +254,12 @@ const entries = [
         "reason": "unsupported_component",
         "rule_id": "core/input.unsupported_component"
     },
+    {
+        "kind": "core",
+        "layer": "internal",
+        "reason": "internal",
+        "rule_id": "core/internal.internal"
+    },
     {
         "kind": "core",
         "layer": "key",
@@ -355,6 +362,12 @@ const entries = [
         "reason": "binding_unsatisfied",
         "rule_id": "core/quorum.binding_unsatisfied"
     },
+    {
+        "kind": "core",
+        "layer": "quorum",
+        "reason": "deadline",
+        "rule_id": "core/quorum.deadline"
+    },
     {
         "kind": "core",
         "layer": "quorum",
@@ -705,6 +718,11 @@ const entries = [
         "reason": "invalid_key",
         "rule_id": "crypto/invalid_key"
     },
+    {
+        "kind": "crypto",
+        "reason": "invalid_options",
+        "rule_id": "crypto/invalid_options"
+    },
     {
         "kind": "crypto",
         "reason": "invalid_signature",
@@ -860,6 +878,11 @@ const entries = [
         "reason": "directory_unsigned",
         "rule_id": "discovery/directory_unsigned"
     },
+    {
+        "kind": "discovery",
+        "reason": "domain_not_found",
+        "rule_id": "discovery/domain_not_found"
+    },
     {
         "kind": "discovery",
         "reason": "invalid_key_set",
@@ -1239,6 +1262,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "deadline": {
+            "kind": "constant",
+            "value": true
+        },
         "digest_mismatch": {
             "kind": "constant",
             "value": false
@@ -1267,6 +1294,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "internal": {
+            "kind": "constant",
+            "value": false
+        },
         "invalid_accept_signature": {
             "kind": "constant",
             "value": false
@@ -1713,6 +1744,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "invalid_options": {
+            "kind": "constant",
+            "value": false
+        },
         "invalid_signature": {
             "kind": "constant",
             "value": false
@@ -1841,6 +1876,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "domain_not_found": {
+            "kind": "constant",
+            "value": false
+        },
         "invalid_key_set": {
             "kind": "constant",
             "value": false
@@ -1871,7 +1910,7 @@ const retryableRules = {
         },
         "resolution_failed": {
             "kind": "constant",
-            "value": false
+            "value": true
         },
         "revoked_key": {
             "kind": "constant",
@@ -1898,7 +1937,7 @@ const retryableRules = {
             "minimum": 500,
             "maximum": 599,
             "path": "lib/request_seal/discovery.ex",
-            "line": 301
+            "line": 517
         },
         "unknown_key": {
             "kind": "constant",
@@ -2105,9 +2144,11 @@ const retryableRules = {
     }
 };
 export const ERROR_RETRYABLE = Object.freeze(Object.fromEntries(Object.entries(retryableRules).map(([kind, rules]) => [kind, Object.freeze(Object.fromEntries(Object.entries(rules).map(([reason, rule]) => [reason, Object.freeze(rule)])))])));
+/** The pinned reason, layer, and retryability table. */
 export const ERROR_PARITY = Object.freeze(entries.map(entry => Object.freeze(entry)));
 const rules = new Set(ERROR_PARITY.map(e => e.rule_id));
 // A frozen Set still exposes mutation methods; the facade keeps the backing Set private.
+/** The complete set of rule IDs derived from the parity table. */
 export const RULE_IDS = Object.freeze({
     get size() { return rules.size; },
     has: (value) => rules.has(value),

package/dist/errors/types.d.ts

@@ -1,30 +1,37 @@
 import { type Reason, type Layer } from './parity.ts';
-export type CoreDetail = Reason<'core'> | Reason<'signature_base'> | 'legacy_string' | 'invalid_dictionary' | 'duplicate_member' | 'invalid_member' | 'missing_member' | 'unsupported_type' | 'not_an_origin' | 'untrusted_agent' | 'source_mismatch' | 'revoked_key' | 'source_unavailable' | 'timeout';
+/** The bounded detail vocabulary for core failures. */
+export type CoreDetail = Reason<'core'> | Reason<'signature_base'> | 'legacy_string' | 'invalid_dictionary' | 'duplicate_member' | 'invalid_member' | 'missing_member' | 'unsupported_type' | 'not_an_origin' | 'untrusted_agent' | 'source_mismatch' | 'revoked_key' | 'source_unavailable' | 'timeout' | 'TypeError' | 'RangeError' | 'URIError' | 'EvalError' | 'ReferenceError' | 'SyntaxError' | 'Error' | 'throw';
+/** A core failure with layer, correlation, and optional bounded source. */
 export type CoreError = Readonly<{
     kind: 'core';
     reason: Reason<'core'>;
     layer: Layer<'core'>;
     correlation: string;
-    retryable: false;
+    retryable: boolean;
     detail: CoreDetail | null;
     message: string | null;
     source: CustodyError | null;
 }>;
+/** Error families carrying only a reason. @inline */
 type SimpleKind = 'message' | 'structured_fields' | 'signature_base' | 'digest' | 'crypto';
+/** A reason-only error for message, field, digest, or crypto operations. */
 export type SimpleError<K extends SimpleKind> = Readonly<{
     kind: K;
     reason: Reason<K>;
 }>;
+/** A custody failure with an explicit retryability flag. */
 export type CustodyError = Readonly<{
     kind: 'custody';
     reason: Reason<'custody'>;
     retryable: boolean;
 }>;
+/** A discovery failure with an explicit retryability flag. */
 export type DiscoveryError = Readonly<{
     kind: 'discovery';
     reason: Reason<'discovery'>;
     retryable: boolean;
 }>;
+/** A JOSE failure with layer and explicit retryability. */
 export type JoseError = Readonly<{
     kind: 'jose';
     reason: Reason<'jose'>;
@@ -32,11 +39,13 @@ export type JoseError = Readonly<{
     correlation: null;
     retryable: boolean;
 }>;
+/** A nonretryable replay-store failure. */
 export type ReplayError = Readonly<{
     kind: 'replay';
     reason: Reason<'replay'>;
     retryable: false;
 }>;
+/** A bounded adapter failure with stage, attempt, and optional source. */
 export type AdapterError = Readonly<{
     kind: 'adapter';
     reason: Reason<'adapter'>;
@@ -47,10 +56,14 @@ export type AdapterError = Readonly<{
     correlation: string;
     retryable: false;
 }>;
+/** The union of all branded, bounded public error families. */
 export type RequestSealError = CoreError | {
     [K in SimpleKind]: SimpleError<K>;
 }[SimpleKind] | CustodyError | DiscoveryError | JoseError | ReplayError | AdapterError;
+/** Check whether an error belongs to the private error brand. */
 export declare function isRequestSealError(value: unknown): value is RequestSealError;
+/** The bounded exception class for an internal-fault detail. */
+export declare function faultClass(e: unknown): CoreDetail;
 export declare function coreError(reason: Reason<'core'>, layer: Layer<'core'>, detail?: CoreDetail | null, source?: CustodyError | null): CoreError;
 export declare const messageError: (reason: Reason<'message'>) => Readonly<{
     kind: "message";
@@ -70,12 +83,13 @@ export declare const digestError: (reason: Reason<'digest'>) => Readonly<{
 }>;
 export declare const cryptoError: (reason: Reason<'crypto'>) => Readonly<{
     kind: "crypto";
-    reason: "invalid_data" | "invalid_key" | "invalid_signature" | "key_mismatch" | "unsupported_algorithm" | "unsupported_format";
+    reason: "invalid_data" | "invalid_key" | "invalid_options" | "invalid_signature" | "key_mismatch" | "unsupported_algorithm" | "unsupported_format";
 }>;
 export declare function custodyError(reason: Reason<'custody'>): CustodyError;
 export declare function discoveryError(reason: Reason<'discovery'>, status?: number): DiscoveryError;
 export declare function joseError(reason: Reason<'jose'>, layer: Layer<'jose'>): JoseError;
 export declare function replayError(reason: Reason<'replay'>): ReplayError;
 export declare function adapterError(reason: Reason<'adapter'>, adapter: AdapterError['adapter'], stage: AdapterError['stage'], attempt: number, source?: AdapterError['source']): AdapterError;
+/** Format an error's family, layer when present, and reason as a rule ID. */
 export declare function ruleId(error: RequestSealError): string;
 export {};

package/dist/errors/types.js

@@ -4,6 +4,7 @@ const addError = errors.add.bind(errors), hasError = errors.has.bind(errors);
 const random = globalThis.crypto.getRandomValues.bind(globalThis.crypto);
 function correlation() { return Array.from(random(new Uint8Array(8)), b => b.toString(16).padStart(2, '0')).join(''); }
 function freeze(error) { addError(error); return Object.freeze(error); }
+/** Check whether an error belongs to the private error brand. */
 export function isRequestSealError(value) { return typeof value === 'object' && value !== null && hasError(value); }
 function reasonFor(kind, reason) {
     if (!ERROR_PARITY.some(e => e.kind === kind && e.reason === reason))
@@ -13,13 +14,25 @@ function reasonFor(kind, reason) {
 const signatureDetails = new Set(['limit', 'wrong_message_kind', 'missing_request_context', 'unavailable_origin', 'unavailable_trailers', 'missing_field', 'non_ascii', 'unknown_field_schema', 'invalid_field_schema', 'invalid_structured_field', 'missing_dictionary_key', 'noncanonical_query_name', 'invalid_query_encoding', 'missing_query_parameter', 'ambiguous_query_parameter']);
 const agentDetails = new Set(['missing_member', 'unsupported_type', 'not_an_origin', 'untrusted_agent', 'source_mismatch', 'unknown_key', 'revoked_key', 'source_unavailable', 'timeout']);
 const fieldDetails = new Set(['legacy_string', 'invalid_dictionary', 'duplicate_member', 'invalid_member']);
+// The bounded exception-class vocabulary an internal fault can name: the
+// global error classes, a closed "Error" for any other Error subclass, and
+// "throw" for non-error throws. No message or stack text ever enters a detail.
+const internalDetails = new Set(['TypeError', 'RangeError', 'URIError', 'EvalError', 'ReferenceError', 'SyntaxError', 'Error', 'throw']);
+/** The bounded exception class for an internal-fault detail. */
+export function faultClass(e) {
+    if (e instanceof Error) {
+        const name = e.constructor?.name;
+        return typeof name === "string" && internalDetails.has(name) ? name : "Error";
+    }
+    return "throw";
+}
 export function coreError(reason, layer, detail = null, source = null) {
     if (!ERROR_PARITY.some(e => e.kind === 'core' && e.layer === layer && e.reason === reason))
         throw new TypeError('Unknown core error pair');
     if (source !== null && (reason !== 'signing_failed' || !isRequestSealError(source) || source.kind !== 'custody'))
         throw new TypeError('Invalid core source');
-    const allowed = reason === 'signature_base_failed' ? signatureDetails : reason === 'agent_unresolved' ? agentDetails : reason === 'invalid_signature_agent' ? fieldDetails : reason === 'nonqualifying_signature' ? new Set(ERROR_PARITY.filter(e => e.kind === 'core').map(e => e.reason)) : new Set();
-    return freeze({ kind: 'core', reason, layer, correlation: correlation(), retryable: false, source, message: reason === 'signer_algorithm_mismatch' ? 'signer algorithm does not match signature specification' : null, detail: typeof detail === 'string' && allowed.has(detail) ? detail : null });
+    const allowed = reason === 'signature_base_failed' ? signatureDetails : reason === 'agent_unresolved' ? agentDetails : reason === 'invalid_signature_agent' ? fieldDetails : reason === 'internal' ? internalDetails : reason === 'nonqualifying_signature' ? new Set(ERROR_PARITY.filter(e => e.kind === 'core').map(e => e.reason)) : new Set();
+    return freeze({ kind: 'core', reason, layer, correlation: correlation(), retryable: reason === 'deadline', source, message: reason === 'signer_algorithm_mismatch' ? 'signer algorithm does not match signature specification' : null, detail: typeof detail === 'string' && allowed.has(detail) ? detail : null });
 }
 function simple(kind, reason) {
     return freeze({ kind, reason: reasonFor(kind, reason) });
@@ -58,4 +71,5 @@ export function adapterError(reason, adapter, stage, attempt, source = null) {
         throw new TypeError('Invalid adapter source');
     return freeze({ kind: 'adapter', reason, adapter, stage, attempt, source, correlation: correlation(), retryable: false });
 }
+/** Format an error's family, layer when present, and reason as a rule ID. */
 export function ruleId(error) { return 'layer' in error ? `${error.kind}/${error.layer}.${error.reason}` : `${error.kind}/${error.reason}`; }

package/dist/index.d.ts

@@ -45,3 +45,4 @@ export { verifyQuorum } from './verify-quorum.ts';
 export { isQuorumVerification } from './quorum/verification.ts';
 export type { QuorumVerification } from './quorum/verification.ts';
 export * from './web-bot-auth/index.ts';
+export { Profile, type ProfileStamp, type ProfileMetadataValue, type SignatureDictionaries } from './profile.ts';

package/dist/index.js

@@ -33,3 +33,4 @@ export { AcceptSignature, parseAcceptSignature, serializeAcceptSignature, fulfil
 export { verifyQuorum } from './verify-quorum.js';
 export { isQuorumVerification } from './quorum/verification.js';
 export * from './web-bot-auth/index.js';
+export { Profile } from './profile.js';

package/dist/jose/header.d.ts

@@ -1,6 +1,7 @@
 import { type JsonNode } from "../json.ts";
 import { type JoseError } from "../errors/types.ts";
 import { type Result } from "../result.ts";
+/** An ordered JOSE protected-header sequence of JSON members. */
 export type Header = readonly (readonly [string, JsonNode])[];
 export declare function fail(reason: JoseError["reason"], layer?: JoseError["layer"]): never;
 export declare function need(value: unknown, reason: JoseError["reason"], layer?: JoseError["layer"]): asserts value;

package/dist/jose/jwe.d.ts

@@ -1,6 +1,8 @@
 import type { Result } from "../result.ts";
 import { type Header } from "./header.ts";
+/** Check the private brand of an authenticated JWE result. */
 export declare function isJweResult(value: unknown): value is JweResult;
+/** A branded authenticated JWE result that confines plaintext bytes. */
 export declare class JweResult {
     #private;
     readonly algorithm: string;
@@ -13,12 +15,19 @@ export declare class JweResult {
     readonly authorization = "not_evaluated";
     constructor(t: object, algorithm: string, encryption: string, header: Header, protectedPart: string, plaintext: Uint8Array);
     get plaintext(): Uint8Array<ArrayBuffer>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): unknown;
 }
+/** Encrypt content into compact JWE using explicit key-management and content algorithms. */
 export declare function encrypt(protectedPairs: unknown, plaintext: unknown, recipient: unknown, options?: unknown): Promise<Result<string>>;
+/** Authenticate and decrypt compact JWE under an explicit policy. */
 export declare function decrypt(input: unknown, inputPolicy: unknown, options?: unknown): Promise<Result<JweResult>>;
+/** Compact JWE encryption and authenticated decryption operations. */
 export declare const JWE: Readonly<{
+    /** Encrypt content into compact JWE using explicit key-management and content algorithms. */
     encrypt: typeof encrypt;
+    /** Authenticate and decrypt compact JWE under an explicit policy. */
     decrypt: typeof decrypt;
+    /** Check the private brand of the operation result. */
     isResult: typeof isJweResult;
 }>;

package/dist/jose/jwe.js

@@ -1,3 +1,4 @@
+import { denoInspection } from "../brand.js";
 import { encodeJson } from "../json.js";
 import { encodeUtf8 } from "../runtime.js";
 import { encodeBase64Url, decodeBase64Url } from "../bytes.js";
@@ -11,9 +12,11 @@ import { bytes, serialize, parse, compact, headerValue, need, } from "./header.j
 import { JWE_ALGORITHMS, ENCRYPTION, context, policy, resolve, selected, bounded, publicSafe, alive, take, ok, err, } from "./support.js";
 import { random, wrapPublic } from "./key-management.js";
 const branded = new WeakSet(), token = Object.freeze({});
+/** Check the private brand of an authenticated JWE result. */
 export function isJweResult(value) {
     return typeof value === "object" && value !== null && branded.has(value);
 }
+/** A branded authenticated JWE result that confines plaintext bytes. */
 export class JweResult {
     algorithm;
     encryption;
@@ -38,6 +41,7 @@ export class JweResult {
     get plaintext() {
         return new Uint8Array(this.#plaintext);
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({
             algorithm: this.algorithm,
@@ -51,8 +55,8 @@ export class JweResult {
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toJSON();
     }
-    [Symbol.for("Deno.customInspect")]() {
-        return this.toJSON();
+    [Symbol.for("Deno.customInspect")](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(JweResult.prototype);
@@ -71,6 +75,7 @@ function encryptedKey(alg, ek, h) {
     else
         need(ek.length >= 256 && ek.length <= 1024, "decryption_failed", "crypto");
 }
+/** Encrypt content into compact JWE using explicit key-management and content algorithms. */
 export async function encrypt(protectedPairs, plaintext, recipient, options = {}) {
     return publicSafe(async () => {
         const c = context(options, 5000, true), data = bytes(plaintext), initial = take(serialize(protectedPairs)), alg = selected(initial.header, JWE_ALGORITHMS, ENCRYPTION), enc = headerValue(initial.header, "enc");
@@ -152,6 +157,7 @@ export async function encrypt(protectedPairs, plaintext, recipient, options = {}
         }, "signer_failed");
     });
 }
+/** Authenticate and decrypt compact JWE under an explicit policy. */
 export async function decrypt(input, inputPolicy, options = {}) {
     return publicSafe(async () => {
         const p = policy(inputPolicy, "jwe"), c = context(options, p.timeout);
@@ -252,4 +258,12 @@ export async function decrypt(input, inputPolicy, options = {}) {
         }, "decryption_failed");
     });
 }
-export const JWE = Object.freeze({ encrypt, decrypt, isResult: isJweResult });
+/** Compact JWE encryption and authenticated decryption operations. */
+export const JWE = Object.freeze({
+    /** Encrypt content into compact JWE using explicit key-management and content algorithms. */
+    encrypt,
+    /** Authenticate and decrypt compact JWE under an explicit policy. */
+    decrypt,
+    /** Check the private brand of the operation result. */
+    isResult: isJweResult
+});

package/dist/jose/jws.d.ts

@@ -1,6 +1,8 @@
 import type { Result } from "../result.ts";
 import { type Header } from "./header.ts";
+/** Check the private brand of a verified JWS result. */
 export declare function isJwsResult(value: unknown): value is JwsResult;
+/** A branded verified JWS result that confines payload bytes. */
 export declare class JwsResult {
     #private;
     readonly algorithm: string;
@@ -11,14 +13,23 @@ export declare class JwsResult {
     readonly authorization = "not_evaluated";
     constructor(t: object, algorithm: string, header: Header, protectedPart: string, payload: Uint8Array);
     get payload(): Uint8Array<ArrayBuffer>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): unknown;
 }
+/** Sign a compact JWS with an explicit algorithm and caller-owned signer. */
 export declare function sign(protectedPairs: unknown, payload: unknown, handle: unknown, options?: unknown): Promise<Result<string>>;
+/** Sign a compact JWS while preserving the supplied protected-header bytes. */
 export declare function signProtected(protectedBytes: unknown, payload: unknown, handle: unknown, options?: unknown): Promise<Result<string>>;
+/** Verify a compact JWS under an explicit algorithm and key policy. */
 export declare function verify(input: unknown, inputPolicy: unknown, options?: unknown): Promise<Result<JwsResult>>;
+/** Compact JWS signing and verification operations. */
 export declare const JWS: Readonly<{
+    /** Sign a compact JWS with an explicit algorithm and caller-owned signer. */
     sign: typeof sign;
+    /** Sign a compact JWS while preserving the supplied protected-header bytes. */
     signProtected: typeof signProtected;
+    /** Verify a compact JWS under an explicit algorithm and key policy. */
     verify: typeof verify;
+    /** Check the private brand of the operation result. */
     isResult: typeof isJwsResult;
 }>;

package/dist/jose/jws.js

@@ -1,3 +1,4 @@
+import { denoInspection } from "../brand.js";
 import { encodeBase64Url, decodeBase64Url } from "../bytes.js";
 import { encodeUtf8 } from "../runtime.js";
 import { isKeyHandle } from "../key_handle.js";
@@ -10,9 +11,11 @@ import { joseError, isRequestSealError } from "../errors/types.js";
 import { bytes, json, serialize, parse, compact, need, } from "./header.js";
 import { JWS_ALGORITHMS, context, policy, resolve, selected, bounded, publicSafe, alive, take, ok, err, } from "./support.js";
 const branded = new WeakSet(), token = Object.freeze({});
+/** Check the private brand of a verified JWS result. */
 export function isJwsResult(value) {
     return typeof value === "object" && value !== null && branded.has(value);
 }
+/** A branded verified JWS result that confines payload bytes. */
 export class JwsResult {
     algorithm;
     header;
@@ -34,6 +37,7 @@ export class JwsResult {
     get payload() {
         return new Uint8Array(this.#payload);
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({
             algorithm: this.algorithm,
@@ -45,8 +49,8 @@ export class JwsResult {
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toJSON();
     }
-    [Symbol.for("Deno.customInspect")]() {
-        return this.toJSON();
+    [Symbol.for("Deno.customInspect")](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(JwsResult.prototype);
@@ -106,6 +110,7 @@ async function signing(protectedPart, h, payload, handle, c) {
         data.fill(0);
     }
 }
+/** Sign a compact JWS with an explicit algorithm and caller-owned signer. */
 export async function sign(protectedPairs, payload, handle, options = {}) {
     return publicSafe(async () => {
         const c = context(options, 5000, true);
@@ -120,6 +125,7 @@ export async function sign(protectedPairs, payload, handle, options = {}) {
         }
     });
 }
+/** Sign a compact JWS while preserving the supplied protected-header bytes. */
 export async function signProtected(protectedBytes, payload, handle, options = {}) {
     return publicSafe(async () => {
         const c = context(options, 5000, true);
@@ -134,6 +140,7 @@ export async function signProtected(protectedBytes, payload, handle, options = {
         }
     });
 }
+/** Verify a compact JWS under an explicit algorithm and key policy. */
 export async function verify(input, inputPolicy, options = {}) {
     return publicSafe(async () => {
         const p = policy(inputPolicy, "jws"), c = context(options, p.timeout);
@@ -183,9 +190,14 @@ export async function verify(input, inputPolicy, options = {}) {
         }, "invalid_signature");
     });
 }
+/** Compact JWS signing and verification operations. */
 export const JWS = Object.freeze({
+    /** Sign a compact JWS with an explicit algorithm and caller-owned signer. */
     sign,
+    /** Sign a compact JWS while preserving the supplied protected-header bytes. */
     signProtected,
+    /** Verify a compact JWS under an explicit algorithm and key policy. */
     verify,
+    /** Check the private brand of the operation result. */
     isResult: isJwsResult,
 });

package/dist/jose/key-management.d.ts

@@ -4,10 +4,12 @@ import { type PublicKey } from "../public_key.ts";
 import { type KeyHandle } from "../key_handle.ts";
 import { type Result } from "../result.ts";
 import { type Header } from "./header.ts";
+/** Owned encrypted-key and content-encryption-key bytes from key wrapping. */
 export type WrapResult = Readonly<{
     encrypted_key: Uint8Array<ArrayBuffer>;
     header: Header;
 }>;
+/** Check the private brand of a JOSE key-management handle. */
 export declare function isKeyManagementHandle(value: unknown): value is KeyManagementHandle;
 /** Caller-owned custodian primitives. RSA private and AES keys never escape as
  * CryptoKey references. Primitive decrypt releases bytes only after authentication. */
@@ -15,16 +17,25 @@ export declare class KeyManagementHandle {
     #private;
     readonly algorithm: string;
     private constructor();
+    /** Import caller-owned local key material into a confined capability. */
     static local(algorithm: unknown, material: unknown): Promise<Result<KeyManagementHandle>>;
+    /** Wrap a generated content-encryption key with the bound key-management algorithm. */
     wrap(algorithm: unknown, content: unknown, context?: Context): Promise<Result<WrapResult>>;
+    /** Authenticate and decrypt content using the bound direct-encryption key. */
     decrypt(encryptedKey: unknown, header: Header, context?: Context): Promise<Result<Uint8Array<ArrayBuffer>>>;
+    /** Confine an unwrapped content-encryption key in a decryption capability. */
     unwrap(encryptedKey: unknown, header: Header, context?: Context): Promise<Result<UnwrappedKey>>;
+    /** Release retained key-management custody and invalidate the capability. */
     release(): Promise<Result<true>>;
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON(): unknown;
 }
 export declare function random(length: number): Uint8Array<ArrayBuffer>;
 export declare function wrapPublic(key: PublicKey | KeyHandle, algorithm: string, content: Uint8Array, context: Context): Promise<Result<WrapResult>>;
+/** Constructors and branding checks for JOSE key-management capabilities. */
 export declare const KeyManagement: Readonly<{
+    /** Import caller-owned local key material into a confined capability. */
     local: typeof KeyManagementHandle.local;
+    /** Check the private brand of a key-management capability. */
     isHandle: typeof isKeyManagementHandle;
 }>;

package/dist/jose/key-management.js

@@ -1,3 +1,4 @@
+import { denoInspection } from "../brand.js";
 import { now } from "../runtime.js";
 import { isContext, withDeadline } from "../context.js";
 import { Custody } from "../custody/index.js";
@@ -14,6 +15,7 @@ import { resolveAlgorithm, importParameters } from "../crypto/algorithm.js";
 import { bytes, headerValue, need, take } from "./header.js";
 import { bounded, publicSafe, alive, JWE_ALGORITHMS } from "./support.js";
 const branded = new WeakSet(), token = Object.freeze({});
+/** Check the private brand of a JOSE key-management handle. */
 export function isKeyManagementHandle(value) {
     return typeof value === "object" && value !== null && branded.has(value);
 }
@@ -32,6 +34,7 @@ export class KeyManagementHandle {
         branded.add(this);
         Object.freeze(this);
     }
+    /** Import caller-owned local key material into a confined capability. */
     static async local(algorithm, material) {
         return publicSafe(async () => {
             need(typeof algorithm === "string" && JWE_ALGORITHMS.includes(algorithm), "algorithm_not_permitted");
@@ -96,6 +99,7 @@ export class KeyManagementHandle {
             }
         });
     }
+    /** Wrap a generated content-encryption key with the bound key-management algorithm. */
     async wrap(algorithm, content, context) {
         return publicSafe(async () => {
             need(algorithm === this.algorithm && this.algorithm.endsWith("GCMKW"), "algorithm_mismatch", "key");
@@ -128,6 +132,7 @@ export class KeyManagementHandle {
             }, "signer_failed");
         });
     }
+    /** Authenticate and decrypt content using the bound direct-encryption key. */
     async decrypt(encryptedKey, header, context) {
         return publicSafe(async () => {
             const c = context === undefined ? take(withDeadline()) : context;
@@ -170,6 +175,7 @@ export class KeyManagementHandle {
             }, "decryption_failed");
         });
     }
+    /** Confine an unwrapped content-encryption key in a decryption capability. */
     async unwrap(encryptedKey, header, context) {
         return publicSafe(async () => {
             const c = context === undefined ? take(withDeadline()) : context;
@@ -214,10 +220,12 @@ export class KeyManagementHandle {
             }, "decryption_failed");
         });
     }
+    /** Release retained key-management custody and invalidate the capability. */
     async release() {
         this.#key = undefined;
         return ok(true);
     }
+    /** Return a bounded public inspection view without retained cryptographic bytes. */
     toJSON() {
         return Object.freeze({
             kind: "KeyManagementHandle",
@@ -227,8 +235,8 @@ export class KeyManagementHandle {
     [Symbol.for("nodejs.util.inspect.custom")]() {
         return this.toJSON();
     }
-    [Symbol.for("Deno.customInspect")]() {
-        return this.toJSON();
+    [Symbol.for("Deno.customInspect")](render) {
+        return denoInspection(render, this.toJSON());
     }
 }
 Object.freeze(KeyManagementHandle.prototype);
@@ -259,7 +267,10 @@ export async function wrapPublic(key, algorithm, content, context) {
         return ok(Object.freeze({ encrypted_key: encrypted, header: Object.freeze([]) }));
     }, "signer_failed");
 }
+/** Constructors and branding checks for JOSE key-management capabilities. */
 export const KeyManagement = Object.freeze({
+    /** Import caller-owned local key material into a confined capability. */
     local: KeyManagementHandle.local,
+    /** Check the private brand of a key-management capability. */
     isHandle: isKeyManagementHandle,
 });

package/dist/jose/nested.d.ts

@@ -1,14 +1,20 @@
 import { type Result } from "../result.ts";
 import { type JweResult } from "./jwe.ts";
 import { type JwsResult } from "./jws.ts";
+/** A branded pair of authenticated outer JWE and verified inner JWS results. */
 export type NestedResult = Readonly<{
     jwe: JweResult;
     jws: JwsResult;
 }>;
+/** Check the private brand of a nested JOSE result. */
 export declare function isNestedResult(value: unknown): value is NestedResult;
 export declare function innerCompact(input: Uint8Array): Result<readonly string[]>;
+/** Authenticate an outer JWE and verify its inner compact JWS. */
 export declare function decrypt(input: unknown, policy: unknown, options: unknown): Promise<Result<NestedResult>>;
+/** One-level nested JWE decryption and JWS verification operations. */
 export declare const Nested: Readonly<{
+    /** Authenticate an outer JWE and verify its inner compact JWS. */
     decrypt: typeof decrypt;
+    /** Check the private brand of the operation result. */
     isResult: typeof isNestedResult;
 }>;