@shelbyb/daywalker-sdk 0.3.0 → 0.4.0

package/dist/crypto/encoding.d.ts

@@ -8,6 +8,11 @@ export declare function bytesToBase64(bytes: Uint8Array): string;
 export declare function base64ToBytes(b64: string): Uint8Array;
 export declare function bytesToBase64Url(bytes: Uint8Array): string;
 export declare function base64UrlToBytes(b64url: string): Uint8Array;
+/**
+ * Decodes unpadded base64url (RFC 7515 §2) strictly: only `[A-Za-z0-9_-]` and only the canonical encoding
+ * of the bytes, so a token or signature has exactly one accepted spelling. Throws otherwise.
+ */
+export declare function base64UrlToBytesStrict(b64url: string): Uint8Array;
 export declare function bytesToHex(bytes: Uint8Array): string;
 export declare function hexToBytes(hex: string): Uint8Array;
 /**

package/dist/crypto/encoding.js

@@ -47,6 +47,20 @@ export function base64UrlToBytes(b64url) {
     }
     return base64ToBytes(b64);
 }
+/**
+ * Decodes unpadded base64url (RFC 7515 §2) strictly: only `[A-Za-z0-9_-]` and only the canonical encoding
+ * of the bytes, so a token or signature has exactly one accepted spelling. Throws otherwise.
+ */
+export function base64UrlToBytesStrict(b64url) {
+    if (!/^[A-Za-z0-9_-]*$/.test(b64url) || b64url.length % 4 === 1) {
+        throw new Error("Invalid base64url encoding");
+    }
+    const bytes = base64UrlToBytes(b64url);
+    if (bytesToBase64Url(bytes) !== b64url) {
+        throw new Error("Non-canonical base64url encoding");
+    }
+    return bytes;
+}
 export function bytesToHex(bytes) {
     let hex = "";
     for (let i = 0; i < bytes.length; i++) {

package/dist/crypto/index.d.ts

@@ -1,5 +1,5 @@
-export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, timingSafeEqual, timingSafeEqualString, maskSecret, redactSecrets, } from "./encoding.js";
+export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, timingSafeEqual, timingSafeEqualString, maskSecret, redactSecrets, } from "./encoding.js";
 export { DEFAULT_MAX_BODY_SIZE_BYTES, computeContentDigest, sha256Base64, sha256Base64Url, } from "./digest.js";
 export { calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, } from "./keys.js";
-export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, } from "./signatures.js";
-export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, } from "./signatures.js";
+export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, } from "./signatures.js";
+export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, ReplayStore, } from "./signatures.js";

package/dist/crypto/index.js

@@ -1,4 +1,4 @@
-export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, bytesToHex, hexToBytes, timingSafeEqual, timingSafeEqualString, maskSecret, redactSecrets, } from "./encoding.js";
+export { stringToUtf8, utf8ToString, bytesToBase64, base64ToBytes, bytesToBase64Url, base64UrlToBytes, base64UrlToBytesStrict, bytesToHex, hexToBytes, timingSafeEqual, timingSafeEqualString, maskSecret, redactSecrets, } from "./encoding.js";
 export { DEFAULT_MAX_BODY_SIZE_BYTES, computeContentDigest, sha256Base64, sha256Base64Url, } from "./digest.js";
 export { calculateJwkThumbprint, generateSigningKey, loadSigningKey, loadPublicKey, } from "./keys.js";
-export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, } from "./signatures.js";
+export { SIGNATURE_VERSION, SIGNATURE_LABEL, SIGNATURE_ALG, MAX_CLOCK_SKEW_SECONDS, REPLAY_CACHE_MAX_ENTRIES, SignatureReplayCache, formatSignatureParams, createSignatureBase, signRequest, verifyRequestSignature, verifyJwtLease, registerPublicKey, } from "./signatures.js";

package/dist/crypto/keys.d.ts

@@ -1,4 +1,4 @@
-import type { PublicJwk, SigningKey } from "../types.js";
+import type { PublicJwk, PublicJwks, SigningKey } from "../types.js";
 /**
  * Calculate the RFC 7638 JWK thumbprint for an Ed25519 public key.
  */
@@ -17,9 +17,9 @@ export declare function generateSigningKey(): Promise<SigningKey>;
  */
 export declare function loadSigningKey(raw: string | SigningKey): Promise<SigningKey>;
 /**
- * Load an Ed25519 public key from JWK, PEM, Base64 SPKI, or Base64url raw public key.
+ * Load an Ed25519 public key from JWK, JWKS (selected by `kid`), PEM, Base64 SPKI, or Base64url raw public key.
  */
-export declare function loadPublicKey(raw: string | PublicJwk | CryptoKey): Promise<{
+export declare function loadPublicKey(raw: string | PublicJwk | PublicJwks | CryptoKey, kid?: string): Promise<{
     publicKey: CryptoKey;
     publicJwk: PublicJwk;
 }>;

package/dist/crypto/keys.js

@@ -131,9 +131,27 @@ export async function loadSigningKey(raw) {
     };
 }
 /**
- * Load an Ed25519 public key from JWK, PEM, Base64 SPKI, or Base64url raw public key.
+ * Picks the Ed25519 key with this `kid` from a JWKS, or its only Ed25519 key (the signature check still
+ * has to pass against it). Several keys and no matching `kid` is an error rather than a guess.
  */
-export async function loadPublicKey(raw) {
+function selectJwk(jwks, kid) {
+    const keys = (Array.isArray(jwks.keys) ? jwks.keys : []).filter((k) => !!k && typeof k === "object" && k.kty === "OKP" && k.crv === "Ed25519");
+    const byKid = kid ? keys.find((k) => k.kid === kid) : undefined;
+    if (byKid)
+        return byKid;
+    if (keys.length === 1)
+        return keys[0];
+    if (keys.length === 0)
+        throw new Error("JWKS contains no Ed25519 keys");
+    throw new Error(kid ? `No key in JWKS matches kid "${kid}"` : "JWKS has several keys and the signature names no kid");
+}
+/**
+ * Load an Ed25519 public key from JWK, JWKS (selected by `kid`), PEM, Base64 SPKI, or Base64url raw public key.
+ */
+export async function loadPublicKey(raw, kid) {
+    if (typeof raw === "object" && raw && "keys" in raw) {
+        return loadPublicKey(selectJwk(raw, kid));
+    }
     if (typeof raw === "object" && "type" in raw && raw.type === "public") {
         const exported = (await globalThis.crypto.subtle.exportKey("jwk", raw));
         const kid = exported.kid || (await calculateJwkThumbprint({ crv: "Ed25519", kty: "OKP", x: exported.x }));
@@ -170,16 +188,19 @@ export async function loadPublicKey(raw) {
     const trimmed = raw.trim();
     // Try parsing as JSON JWK or JWKS
     if (trimmed.startsWith("{")) {
+        let parsed;
         try {
-            const parsed = JSON.parse(trimmed);
-            const jwkCandidate = parsed.keys ? parsed.keys[0] : parsed;
-            if (jwkCandidate && jwkCandidate.kty === "OKP" && jwkCandidate.crv === "Ed25519") {
-                return loadPublicKey(jwkCandidate);
-            }
+            parsed = JSON.parse(trimmed);
         }
         catch {
             // Continue
         }
+        if (parsed && typeof parsed === "object") {
+            const jwkCandidate = parsed.keys ? selectJwk(parsed, kid) : parsed;
+            if (jwkCandidate.kty === "OKP" && jwkCandidate.crv === "Ed25519") {
+                return loadPublicKey(jwkCandidate);
+            }
+        }
     }
     // Handle PEM / Base64 / Base64url
     let cleaned = trimmed

package/dist/crypto/signatures.d.ts

@@ -1,38 +1,57 @@
-import type { PublicJwk, SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult } from "../types.js";
+import type { PublicJwk, PublicJwks, ReplayStore, SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult } from "../types.js";
 export declare const SIGNATURE_VERSION = "rfc9421";
 export declare const SIGNATURE_LABEL = "sig1";
 export declare const SIGNATURE_ALG = "ed25519";
 export declare const MAX_CLOCK_SKEW_SECONDS = 300;
 export declare const SAFE_IDENTIFIER_PATTERN: RegExp;
 /**
- * Normalizes HTTP request path per RFC 3986 to prevent path traversal & signature confusion.
+ * Splits a request target into its RFC 9421 "@path" value (§2.2.6; dot segments resolved and repeated
+ * slashes collapsed per RFC 3986, to prevent path traversal & signature confusion) and its "@query" value
+ * (§2.2.7; the query with its leading "?", or "?" alone when there is none). Fragments are dropped.
+ */
+export declare function splitRequestTarget(rawTarget: string): {
+    path: string;
+    query: string;
+};
+/**
+ * Normalizes an HTTP request path per RFC 3986 into the "@path" component. Path only: the query string is
+ * a separate "@query" component (see `splitRequestTarget`).
  */
 export declare function normalizePath(rawPath: string): string;
 /**
  * Validates that an identifier (keyId, serviceSlug, etc.) contains only safe alphanumeric/hyphen characters.
  */
 export declare function assertSafeIdentifier(name: string, value: string): void;
-/** Upper bound on remembered signatures; the oldest entries are evicted past this. */
-export declare const REPLAY_CACHE_MAX_ENTRIES = 10000;
+/**
+ * Upper bound on remembered signatures. Unexpired entries are never evicted: once the cache is full of them,
+ * new signatures are rejected (fail closed) until entries expire. Entries live 2 x maxClockSkewSeconds
+ * (600s by default), so the default sustains ~160 verified requests/s per process.
+ */
+export declare const REPLAY_CACHE_MAX_ENTRIES = 100000;
 /**
  * In-memory replay cache, keyed on keyid + decoded signature bytes (so re-encodings of the
- * same signature collide). Insertion-ordered, so eviction drops the oldest entries first.
+ * same signature collide). Per process only: multi-instance deployments need a shared `ReplayStore`.
  */
-export declare class SignatureReplayCache {
+export declare class SignatureReplayCache implements ReplayStore {
     private readonly maxEntries;
     private seen;
     constructor(maxEntries?: number);
     get size(): number;
     /** True when the key was recorded and has not expired yet (a replay). */
     has(key: string, now?: number): boolean;
-    record(key: string, ttlMs: number, now?: number): void;
+    /**
+     * Records `key` until `now + ttlMs`. Returns false, recording nothing, when the key is already present
+     * or the cache is full of unexpired entries (a still-valid signature is never forgotten early).
+     */
+    record(key: string, ttlMs: number, now?: number): boolean;
     clear(): void;
 }
 export declare const globalReplayCache: SignatureReplayCache;
-export type { SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, };
+export type { ReplayStore, SignedHeaders, SignRequestParams, VerifySignatureParams, VerifySignatureResult, };
 /**
  * Format the RFC 9421 Signature-Input parameters string.
  * Example: `("@method" "@path" "@authority" "content-digest");created=1791561600;keyid="...";alg="ed25519";nonce="..."`
+ * Every value is validated, so none can close its quoted string and inject parameters.
  */
 export declare function formatSignatureParams(params: {
     components?: string[];
@@ -42,7 +61,10 @@ export declare function formatSignatureParams(params: {
     nonce?: string;
 }): string;
 /**
- * Construct canonical RFC 9421 signature base string.
+ * Construct canonical RFC 9421 signature base string from the covered components, in order. They are
+ * `components` when given, else the list declared in `signatureParams`. "@path" and "@query" come from
+ * `path` (which may carry a query string); "content-digest" from `contentDigest`; any other header field
+ * from `additionalComponents`. Throws when a covered component has no value.
  */
 export declare function createSignatureBase(params: {
     method: string;
@@ -51,13 +73,19 @@ export declare function createSignatureBase(params: {
     contentDigest?: string | null;
     signatureParams: string;
     additionalComponents?: Record<string, string>;
+    components?: string[];
 }): string;
 /**
  * Sign an outgoing HTTP request according to RFC 9421 + RFC 9530.
+ * Covers "@method", "@path", "@query" (only when `path` has a query string), "@authority" and
+ * "content-digest" (whenever there is a body, and always for POST / PUT / PATCH).
  */
 export declare function signRequest(params: SignRequestParams): Promise<SignedHeaders>;
 /**
- * Verify an incoming RFC 9421 HTTP Message Signature.
+ * Verify an incoming RFC 9421 HTTP Message Signature. The signature base is built from the components the
+ * signature declares, which must include "@method", "@path" and "@authority", plus "@query" when the request
+ * has a query string and "content-digest" when it has a body or is a POST / PUT / PATCH.
+ * Replay protection uses `replayStore` (default: per-process memory; use a shared store across instances).
  */
 export declare function verifyRequestSignature(params: VerifySignatureParams): Promise<VerifySignatureResult>;
 /** Clock skew tolerated on JWT lease `exp` / `nbf`. */
@@ -65,11 +93,13 @@ export declare const JWT_CLOCK_SKEW_SECONDS = 60;
 /**
  * Zero-egress offline verification for asymmetric JWT token leases.
  * Requires a numeric `exp` and an audience (`aud` or `serviceSlug`) equal to `expectedServiceSlug`;
- * a verifier without an expected slug rejects every lease. `iss` is checked when `expectedIssuer` is set.
+ * a verifier without an expected slug rejects every lease. `iss` is checked when `expectedIssuer` is set
+ * (Daywalker documents no fixed issuer, so there is no default). Segments must be canonical unpadded
+ * base64url, a `crit` header is rejected, and a JWKS `publicKey` is searched by the header's `kid`.
  */
 export declare function verifyJwtLease(params: {
     token: string;
-    publicKey: string | PublicJwk | CryptoKey;
+    publicKey: string | PublicJwk | PublicJwks | CryptoKey;
     expectedServiceSlug?: string;
     expectedIssuer?: string;
     currentTime?: number;