@request-seal/core 0.1.0 → 0.2.0

package/dist/discovery/index.d.ts

@@ -1,13 +1,18 @@
 import { type Result } from "../result.ts";
 import { fromSnapshot } from "./snapshot.ts";
 import { type Resolution } from "./body.ts";
+/** A discovery-backed signature key resolver. @inline */
 export type KeyResolver = (request: unknown) => Promise<Result<Readonly<{
     algorithm: Resolution["algorithm"];
     key: Resolution["key"];
 }>>>;
+/** Create a resolver over a branded key set or caller-owned discovery cache. */
 declare function resolver(input: unknown, opts: unknown): Result<KeyResolver>;
+/** Snapshot resolution and explicit discovery operations. */
 export declare const Discovery: Readonly<{
+    /** Create a resolver over a branded key set or caller-owned discovery cache. */
     resolver: typeof resolver & {
+        /** Parse a caller-supplied discovery snapshot without fetching it. */
         fromSnapshot: typeof fromSnapshot;
     };
 }>;

package/dist/discovery/index.js

@@ -5,6 +5,7 @@ import { isDiscoverySource } from "./source.js";
 import { isDiscoveryCache } from "./cache.js";
 import { fromSnapshot } from "./snapshot.js";
 import { ensure, unwrap, failure } from "./support.js";
+/** Create a resolver over a branded key set or caller-owned discovery cache. */
 function resolver(input, opts) {
     try {
         const a = unwrap(snapshotOptions(opts, ["algorithms"]), "invalid_options");
@@ -44,8 +45,15 @@ function resolver(input, opts) {
         return failure(e, "invalid_options");
     }
 }
-const Resolver = Object.freeze(Object.assign(resolver, { fromSnapshot }));
-export const Discovery = Object.freeze({ resolver: Resolver });
+const Resolver = Object.freeze(Object.assign(resolver, {
+    /** Parse a caller-supplied discovery snapshot without fetching it. */
+    fromSnapshot
+}));
+/** Snapshot resolution and explicit discovery operations. */
+export const Discovery = Object.freeze({
+    /** Create a resolver over a branded key set or caller-owned discovery cache. */
+    resolver: Resolver
+});
 export { DiscoverySource, isDiscoverySource, directoryId } from "./source.js";
 export { isKeySet, isResolution, } from "./body.js";
 export { createCache, isDiscoveryCache, } from "./cache.js";

package/dist/discovery/node-connection.d.ts

@@ -3,5 +3,5 @@ export declare function checkPeer(observed: {
     address: string | undefined;
     port: number | undefined;
 }, address: string, port: number, permittedAddresses: readonly string[]): void;
-/** A connected peer denial terminates the address loop. */
+/** Peer and trust-store denials terminate the address loop unchanged. */
 export declare function allowConnectionRetry(error: unknown): void;

package/dist/discovery/node-connection.js

@@ -5,8 +5,8 @@ export function checkPeer(observed, address, port, permittedAddresses) {
     ensure(sameAddress(observed.address, address) && observed.port === port &&
         unwrap(addressAllowed(observed.address, permittedAddresses), "address_denied"), "address_denied");
 }
-/** A connected peer denial terminates the address loop. */
+/** Peer and trust-store denials terminate the address loop unchanged. */
 export function allowConnectionRetry(error) {
-    if (error && typeof error === "object" && "reason" in error && error.reason === "address_denied")
+    if (error && typeof error === "object" && "reason" in error && (error.reason === "address_denied" || error.reason === "transport_unavailable"))
         throw error;
 }

package/dist/discovery/node-trust.d.ts

@@ -0,0 +1,2 @@
+/** Classify OS trust permission failures without changing other errors. */
+export declare function systemCertificateError(error: unknown): never;

package/dist/discovery/node-trust.js

@@ -0,0 +1,9 @@
+import { discoveryError } from '../errors/types.js';
+/** Classify OS trust permission failures without changing other errors. */
+export function systemCertificateError(error) {
+    const deno = globalThis.Deno;
+    const PermissionError = deno?.errors?.NotCapable;
+    if (PermissionError && error instanceof PermissionError)
+        throw discoveryError('transport_unavailable');
+    throw error;
+}

package/dist/discovery/node.d.ts

@@ -1,15 +1,19 @@
 import { type Result } from "../result.ts";
 import { type KeySet } from "./body.ts";
 export type DiscoverySource = import("./source.ts").DiscoverySource;
+/** Fetch a discovery key set with bounded HTTPS, address, and redirect policies. */
 export declare function fetch(source: unknown, input?: unknown): Promise<Result<KeySet>>;
+/** Discovery resolution with the explicit Node HTTPS transport. */
 export declare const Discovery: Readonly<{
     resolver: ((input: unknown, opts: unknown) => Result<import("./index.ts").KeyResolver>) & {
         fromSnapshot: typeof import("./snapshot.ts").fromSnapshot;
     };
+    /** Fetch a discovery key set through the bounded Node HTTPS transport. */
     fetch: typeof fetch;
 }>;
 /** Node source creation fails closed when the OS trust store is unavailable or empty. */
 export declare const DiscoverySource: Readonly<{
     directoryId: typeof import("./source.ts").directoryId;
+    /** Create a discovery source after validating Node transport options. */
     create(input: unknown): Result<import("./source.ts").DiscoverySource>;
 }>;

package/dist/discovery/node.js

@@ -15,6 +15,7 @@ import { fields, header, expiry, mediaType } from "./headers.js";
 import { bodyDocument } from "./body.js";
 import { fromResource } from "./snapshot.js";
 import { decodeBody } from "./gzip.js";
+import { systemCertificateError } from "./node-trust.js";
 import { checkPeer, allowConnectionRetry } from "./node-connection.js";
 const lookup = dns.lookup.bind(dns);
 function remaining(context) {
@@ -58,16 +59,23 @@ async function resolve(host, context, servers) {
         }
     }
     remaining(context);
-    ensure(answers.length >= 1 &&
-        answers.length <= 64 &&
-        answers.every((a) => isIP(a.address) === a.family), "resolution_failed");
-    return [...new Set(answers.map((a) => a.address))];
+    ensure(answers.every((a) => isIP(a.address) === a.family), "resolution_failed");
+    // Match the reference resolver: IPv6 first, retaining order within each family,
+    // then remove duplicates before applying the address bound.
+    const addresses = [...new Set(answers.sort((a, b) => b.family - a.family).map((a) => a.address))];
+    ensure(addresses.length >= 1 && addresses.length <= 64, "resolution_failed");
+    return addresses;
 }
 function systemCertificates() {
     if (typeof tls.getCACertificates !== "function")
         return undefined;
-    const certificates = tls.getCACertificates("system");
-    return certificates.length > 0 ? certificates : undefined;
+    try {
+        const certificates = tls.getCACertificates("system");
+        return certificates.length > 0 ? certificates : undefined;
+    }
+    catch (error) {
+        systemCertificateError(error);
+    }
 }
 function tlsSocket(ip, url, source, context) {
     remaining(context);
@@ -367,6 +375,7 @@ async function resource(url, source, context, servers, hops = 0) {
     remaining(context);
     return { fields: fs, encoded, decoded, location: url.href };
 }
+/** Fetch a discovery key set with bounded HTTPS, address, and redirect policies. */
 export async function fetch(source, input = {}) {
     try {
         ensure(isDiscoverySource(source), "invalid_source");
@@ -446,14 +455,23 @@ export async function fetch(source, input = {}) {
         return failure(error, "invalid_options");
     }
 }
-export const Discovery = Object.freeze({ ...CoreDiscovery, fetch });
+/** Discovery resolution with the explicit Node HTTPS transport. */
+export const Discovery = Object.freeze({ ...CoreDiscovery,
+    /** Fetch a discovery key set through the bounded Node HTTPS transport. */
+    fetch });
 /** Node source creation fails closed when the OS trust store is unavailable or empty. */
 export const DiscoverySource = Object.freeze({
     ...CoreSource,
+    /** Create a discovery source after validating Node transport options. */
     create(input) {
-        const result = CoreSource.create(input);
-        if (result.ok && result.value.cacerts === "os" && !systemCertificates())
-            return err(custodyError("unsupported_format"));
-        return result;
+        try {
+            const result = CoreSource.create(input);
+            if (result.ok && result.value.cacerts === "os" && !systemCertificates())
+                return err(custodyError("unsupported_format"));
+            return result;
+        }
+        catch (error) {
+            return failure(error, "invalid_source");
+        }
     },
 });

package/dist/discovery/source.d.ts

@@ -1,5 +1,7 @@
 import { type Result } from "../result.ts";
+/** Supported discovery source kinds. @inline */
 export type SourceType = "directory" | "jwks_uri" | "cimd";
+/** A branded HTTPS discovery source with bounded transport and cache policies. */
 export type DiscoverySource = Readonly<{
     type: SourceType;
     location: string;
@@ -18,9 +20,11 @@ export type DiscoverySource = Readonly<{
     maxTtl: number;
     negativeTtl: number;
 }>;
+/** Check the private brand of a discovery source. */
 export declare function isDiscoverySource(s: unknown): s is DiscoverySource;
 export declare function sourceIdentity(s: DiscoverySource): string;
 export declare function thumbprintId(value: unknown): value is string;
+/** Check whether a string is a valid directory key identifier. */
 export declare function directoryId(value: unknown): Result<boolean>;
 export declare function keyIdValid(s: DiscoverySource, v: unknown): v is string;
 /** Validate raw spelling before WHATWG normalization can erase a dot segment. */
@@ -29,7 +33,10 @@ export declare function normalizedHost(url: URL): string;
 export declare function sourceOrigin(url: URL): string;
 export declare function sourceAuthority(url: URL): string;
 export declare function createSource(input: unknown): Result<DiscoverySource>;
+/** Discovery source construction and directory identifier validation. */
 export declare const DiscoverySource: Readonly<{
+    /** Snapshot, validate, and brand an HTTPS discovery source. */
     create: typeof createSource;
+    /** Check the directory key identifier syntax. */
     directoryId: typeof directoryId;
 }>;

package/dist/discovery/source.js

@@ -15,6 +15,7 @@ const limits = Object.freeze({
     maxTtl: 86400,
     negativeTtl: 30,
 });
+/** Check the private brand of a discovery source. */
 export function isDiscoverySource(s) {
     return !!s && typeof s === "object" && sources.has(s);
 }
@@ -33,6 +34,7 @@ function validDirectoryId(v) {
         v.length <= 256 &&
         /^[\x20-\x7e]+$/.test(v));
 }
+/** Check whether a string is a valid directory key identifier. */
 export function directoryId(value) {
     return ok(validDirectoryId(value));
 }
@@ -193,7 +195,10 @@ export function createSource(input) {
         return failure(e, "invalid_source");
     }
 }
+/** Discovery source construction and directory identifier validation. */
 export const DiscoverySource = Object.freeze({
+    /** Snapshot, validate, and brand an HTTPS discovery source. */
     create: createSource,
+    /** Check the directory key identifier syntax. */
     directoryId,
 });

package/dist/discovery/support.js

@@ -1,4 +1,4 @@
-import { snapshotOptions, deepFreeze } from "../brand.js";
+import { snapshotOptions, deepFreeze, inspection } from "../brand.js";
 import { discoveryError, isRequestSealError } from "../errors/types.js";
 import { err } from "../result.js";
 export function ensure(value, reason) {
@@ -49,8 +49,7 @@ export function inspectable(value, facts) {
     const inspect = () => Object.freeze({ ...facts });
     Object.defineProperties(value, {
         toJSON: { value: inspect },
-        [Symbol.for("nodejs.util.inspect.custom")]: { value: inspect },
-        [Symbol.for("Deno.customInspect")]: { value: inspect },
+        ...inspection(inspect),
     });
     return Object.freeze(value);
 }

package/dist/errors/parity.d.ts

@@ -1,4 +1,5 @@
-export declare const ELIXIR_ERROR_PIN = "b2392871933d99641a7cb2ca2726aefd20081dee";
+/** The immutable reference release used for the error vocabulary. */
+export declare const ELIXIR_ERROR_PIN = "0a6568aa246326617f760e94e21b359285c6ddfc";
 declare const retryableRules: {
     readonly core: {
         readonly actor_unbound: {
@@ -511,6 +512,10 @@ declare const retryableRules: {
             readonly kind: "constant";
             readonly value: false;
         };
+        readonly invalid_options: {
+            readonly kind: "constant";
+            readonly value: false;
+        };
         readonly invalid_signature: {
             readonly kind: "constant";
             readonly value: false;
@@ -903,6 +908,7 @@ declare const retryableRules: {
     };
 };
 export declare const ERROR_RETRYABLE: typeof retryableRules;
+/** The pinned reason, layer, and retryability table. */
 export declare const ERROR_PARITY: readonly Readonly<{
     readonly kind: "core";
     readonly layer: "binding";
@@ -1480,6 +1486,10 @@ export declare const ERROR_PARITY: readonly Readonly<{
     readonly kind: "crypto";
     readonly reason: "invalid_key";
     readonly rule_id: "crypto/invalid_key";
+} | {
+    readonly kind: "crypto";
+    readonly reason: "invalid_options";
+    readonly rule_id: "crypto/invalid_options";
 } | {
     readonly kind: "crypto";
     readonly reason: "invalid_signature";
@@ -1882,13 +1892,18 @@ export declare const ERROR_PARITY: readonly Readonly<{
     readonly reason: "untrusted_proxy";
     readonly rule_id: "adapter/untrusted_proxy";
 }>[];
+/** A pinned error reason and its layers and retryability metadata. */
 export type ParityEntry = typeof ERROR_PARITY[number];
+/** An error family present in the pinned parity table. */
 export type ErrorKind = ParityEntry["kind"];
+/** The allowed reason vocabulary for an error family. */
 export type Reason<K extends ErrorKind> = Extract<ParityEntry, {
     kind: K;
 }>["reason"];
+/** The allowed layer vocabulary for an error family. */
 export type Layer<K extends "core" | "jose"> = Extract<ParityEntry, {
     kind: K;
 }>["layer"];
+/** The complete set of rule IDs derived from the parity table. */
 export declare const RULE_IDS: ReadonlySet<string>;
 export {};

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 = '0a6568aa246326617f760e94e21b359285c6ddfc';
 const entries = [
     {
         "kind": "core",
@@ -705,6 +706,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",
@@ -1713,6 +1719,10 @@ const retryableRules = {
             "kind": "constant",
             "value": false
         },
+        "invalid_options": {
+            "kind": "constant",
+            "value": false
+        },
         "invalid_signature": {
             "kind": "constant",
             "value": false
@@ -2105,9 +2115,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,5 +1,7 @@
 import { type Reason, type Layer } from './parity.ts';
+/** 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';
+/** A core failure with layer, correlation, and optional bounded source. */
 export type CoreError = Readonly<{
     kind: 'core';
     reason: Reason<'core'>;
@@ -10,21 +12,26 @@ export type CoreError = Readonly<{
     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,9 +56,11 @@ 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;
 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<{
@@ -70,12 +81,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))
@@ -58,4 +59,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;
 }>;