@bradford-tech/supabase-integrity-attest 0.3.1 → 0.3.2

package/README.md

@@ -10,7 +10,7 @@ assertions using the WebCrypto API. Built for Deno and Supabase Edge Functions.
 deno add jsr:@bradford-tech/supabase-integrity-attest
 
 # npm
-npx jsr add @bradford-tech/supabase-integrity-attest
+npm install @bradford-tech/supabase-integrity-attest
 ```
 
 ## Subpath imports

package/esm/assertion.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Lightweight assertion-only entry point. Avoids pulling in `asn1js` and
+ * `@noble/curves`, keeping the bundle minimal for assertion-only use cases.
+ *
+ * ```ts
+ * import { verifyAssertion } from "@bradford-tech/supabase-integrity-attest/assertion";
+ *
+ * const { signCount } = await verifyAssertion(
+ *   { appId: "TEAMID.com.example.app" },
+ *   assertion,
+ *   clientData,
+ *   publicKeyPem,
+ *   previousSignCount,
+ * );
+ * ```
+ *
+ * @module
+ */
 export { verifyAssertion } from "./src/assertion.js";
 export type { AppInfo, AssertionResult } from "./src/assertion.js";
 export { AssertionError, AssertionErrorCode } from "./src/errors.js";

package/esm/assertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../src/assertion.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../src/assertion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC"}

package/esm/assertion.js

@@ -1,4 +1,21 @@
-// assertion.ts — lightweight entry point (no asn1js / @noble/curves)
+/**
+ * Lightweight assertion-only entry point. Avoids pulling in `asn1js` and
+ * `@noble/curves`, keeping the bundle minimal for assertion-only use cases.
+ *
+ * ```ts
+ * import { verifyAssertion } from "@bradford-tech/supabase-integrity-attest/assertion";
+ *
+ * const { signCount } = await verifyAssertion(
+ *   { appId: "TEAMID.com.example.app" },
+ *   assertion,
+ *   clientData,
+ *   publicKeyPem,
+ *   previousSignCount,
+ * );
+ * ```
+ *
+ * @module
+ */
 export { verifyAssertion } from "./src/assertion.js";
 export { AssertionError, AssertionErrorCode } from "./src/errors.js";
 // withAssertion wrapper

package/esm/attestation.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Full attestation entry point including certificate chain verification
+ * dependencies (`asn1js`, `@noble/curves`).
+ *
+ * ```ts
+ * import { verifyAttestation } from "@bradford-tech/supabase-integrity-attest/attestation";
+ *
+ * const { publicKeyPem } = await verifyAttestation(
+ *   { appId: "TEAMID.com.example.app" },
+ *   keyId,
+ *   challenge,
+ *   attestation,
+ * );
+ * ```
+ *
+ * @module
+ */
 export { verifyAttestation } from "./src/attestation.js";
 export type { AppInfo, AttestationResult, VerifyAttestationOptions, } from "./src/attestation.js";
 export { AttestationError, AttestationErrorCode } from "./src/errors.js";

package/esm/attestation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../src/attestation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,OAAO,EACP,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../src/attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,OAAO,EACP,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC"}

package/esm/attestation.js

@@ -1,3 +1,19 @@
-// attestation.ts — full attestation entry point (includes cert chain deps)
+/**
+ * Full attestation entry point including certificate chain verification
+ * dependencies (`asn1js`, `@noble/curves`).
+ *
+ * ```ts
+ * import { verifyAttestation } from "@bradford-tech/supabase-integrity-attest/attestation";
+ *
+ * const { publicKeyPem } = await verifyAttestation(
+ *   { appId: "TEAMID.com.example.app" },
+ *   keyId,
+ *   challenge,
+ *   attestation,
+ * );
+ * ```
+ *
+ * @module
+ */
 export { verifyAttestation } from "./src/attestation.js";
 export { AttestationError, AttestationErrorCode } from "./src/errors.js";

package/esm/mod.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Verify Apple App Attest attestations and assertions using WebCrypto.
+ *
+ * ```ts
+ * import { verifyAttestation, verifyAssertion } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const { publicKeyPem } = await verifyAttestation(
+ *   { appId: "TEAMID.com.example.app" },
+ *   keyId,
+ *   challenge,
+ *   attestation,
+ * );
+ * ```
+ *
+ * @module
+ */
 export type { AppInfo, AttestationResult, VerifyAttestationOptions, } from "./src/attestation.js";
 export type { AssertionResult } from "./src/assertion.js";
 export { verifyAttestation } from "./src/attestation.js";

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,OAAO,EACP,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EACV,OAAO,EACP,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC"}

package/esm/mod.js

@@ -1,4 +1,19 @@
-// mod.ts — public API surface
+/**
+ * Verify Apple App Attest attestations and assertions using WebCrypto.
+ *
+ * ```ts
+ * import { verifyAttestation, verifyAssertion } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const { publicKeyPem } = await verifyAttestation(
+ *   { appId: "TEAMID.com.example.app" },
+ *   keyId,
+ *   challenge,
+ *   attestation,
+ * );
+ * ```
+ *
+ * @module
+ */
 export { verifyAttestation } from "./src/attestation.js";
 export { verifyAssertion } from "./src/assertion.js";
 export { AssertionError, AssertionErrorCode, AttestationError, AttestationErrorCode, } from "./src/errors.js";

package/esm/src/assertion.d.ts

@@ -1,9 +1,23 @@
+/** Identifies the app whose assertions are being verified. */
 export interface AppInfo {
+    /** Apple App ID in the format `TEAMID.bundleId`. */
     appId: string;
+    /** Set to `true` when verifying assertions from the development environment. */
     developmentEnv?: boolean;
 }
+/** Successful assertion verification result. */
 export interface AssertionResult {
+    /** Updated sign count to persist for the next assertion. */
     signCount: number;
 }
+/**
+ * Verify an Apple App Attest assertion.
+ *
+ * Validates the CBOR-encoded assertion against the expected app ID,
+ * checks the monotonic sign counter, and verifies the ECDSA signature
+ * using the device's public key.
+ *
+ * @throws {AssertionError} If any verification step fails.
+ */
 export declare function verifyAssertion(appInfo: AppInfo, assertion: Uint8Array | string, clientData: Uint8Array | string, publicKeyPem: string, previousSignCount: number): Promise<AssertionResult>;
 //# sourceMappingURL=assertion.d.ts.map

package/esm/src/assertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../../src/src/assertion.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,UAAU,EAAE,UAAU,GAAG,MAAM,EAC/B,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,eAAe,CAAC,CA2G1B"}
+{"version":3,"file":"assertion.d.ts","sourceRoot":"","sources":["../../src/src/assertion.ts"],"names":[],"mappings":"AAaA,8DAA8D;AAC9D,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,UAAU,EAAE,UAAU,GAAG,MAAM,EAC/B,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,eAAe,CAAC,CA2G1B"}

package/esm/src/assertion.js

@@ -4,6 +4,15 @@ import { parseAssertionAuthData } from "./authdata.js";
 import { derToRaw } from "./der.js";
 import { AssertionError, AssertionErrorCode } from "./errors.js";
 import { concat, constantTimeEqual, decodeBase64Bytes, importPemPublicKey, toBytes, } from "./utils.js";
+/**
+ * Verify an Apple App Attest assertion.
+ *
+ * Validates the CBOR-encoded assertion against the expected app ID,
+ * checks the monotonic sign counter, and verifies the ECDSA signature
+ * using the device's public key.
+ *
+ * @throws {AssertionError} If any verification step fails.
+ */
 export async function verifyAssertion(appInfo, assertion, clientData, publicKeyPem, previousSignCount) {
     const assertionBytes = decodeBase64Bytes(assertion);
     const clientDataBytes = toBytes(clientData);

package/esm/src/attestation.d.ts

@@ -1,14 +1,22 @@
+/** Identifies the app being attested. */
 export interface AppInfo {
+    /** Apple App ID in the format `TEAMID.bundleId`. */
     appId: string;
+    /** Set to `true` when verifying attestations from the development environment. */
     developmentEnv?: boolean;
 }
+/** Successful attestation verification result. */
 export interface AttestationResult {
+    /** PEM-encoded ECDSA P-256 public key extracted from the attestation. */
     publicKeyPem: string;
+    /** Raw App Attest receipt bytes for server-side refresh. */
     receipt: Uint8Array;
+    /** Initial sign count (always `0` for attestation). */
     signCount: number;
 }
+/** Options for {@linkcode verifyAttestation}. */
 export interface VerifyAttestationOptions {
-    /** Override date for certificate chain validation (for testing with expired certs) */
+    /** Override date for certificate chain validation (for testing with expired certs). */
     checkDate?: Date;
 }
 /**
@@ -32,6 +40,17 @@ export interface AttestationCbor {
     };
     authData: Uint8Array;
 }
+/** Decode an Apple App Attest attestation object from raw CBOR bytes. */
 export declare function decodeAttestationCbor(data: Uint8Array): AttestationCbor;
+/**
+ * Verify an Apple App Attest attestation.
+ *
+ * Implements the full server-side verification described in
+ * [Apple's documentation](https://developer.apple.com/documentation/devicecheck/validating_apps_that_connect_to_your_server):
+ * CBOR decode, certificate chain validation, nonce check, key extraction,
+ * AAGUID check, and credential ID verification.
+ *
+ * @throws {AttestationError} If any verification step fails.
+ */
 export declare function verifyAttestation(appInfo: AppInfo, keyId: string, challenge: Uint8Array | string, attestation: Uint8Array | string, options?: VerifyAttestationOptions): Promise<AttestationResult>;
 //# sourceMappingURL=attestation.d.ts.map

package/esm/src/attestation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../src/src/attestation.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,sFAAsF;IACtF,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QACP,GAAG,EAAE,UAAU,EAAE,CAAC;QAClB,OAAO,EAAE,UAAU,CAAC;KACrB,CAAC;IACF,QAAQ,EAAE,UAAU,CAAC;CACtB;AAsGD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAyEvE;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,WAAW,EAAE,UAAU,GAAG,MAAM,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,iBAAiB,CAAC,CAkJ5B"}
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../src/src/attestation.ts"],"names":[],"mappings":"AAaA,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,OAAO,EAAE,UAAU,CAAC;IACpB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,wBAAwB;IACvC,uFAAuF;IACvF,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QACP,GAAG,EAAE,UAAU,EAAE,CAAC;QAClB,OAAO,EAAE,UAAU,CAAC;KACrB,CAAC;IACF,QAAQ,EAAE,UAAU,CAAC;CACtB;AAsGD,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAyEvE;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,WAAW,EAAE,UAAU,GAAG,MAAM,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,iBAAiB,CAAC,CAkJ5B"}

package/esm/src/attestation.js

@@ -20,10 +20,10 @@ function readCborUint(data, offset) {
     }
     if (additional === 26) {
         return {
-            value: ((data[offset + 1] << 24) >>> 0) +
-                (data[offset + 2] << 16) +
-                (data[offset + 3] << 8) +
-                data[offset + 4],
+            value: ((data[offset + 1] << 24) |
+                (data[offset + 2] << 16) |
+                (data[offset + 3] << 8) |
+                data[offset + 4]) >>> 0,
             end: offset + 5,
         };
     }
@@ -88,6 +88,7 @@ function findCborTextKey(data, key, startOffset) {
     }
     return -1;
 }
+/** Decode an Apple App Attest attestation object from raw CBOR bytes. */
 export function decodeAttestationCbor(data) {
     // Verify top-level is a CBOR map
     const majorType = (data[0] >> 5) & 0x07;
@@ -154,6 +155,16 @@ export function decodeAttestationCbor(data) {
     const { value: authData } = readCborBytes(data, authDataValuePos);
     return { fmt, attStmt: { x5c, receipt }, authData };
 }
+/**
+ * Verify an Apple App Attest attestation.
+ *
+ * Implements the full server-side verification described in
+ * [Apple's documentation](https://developer.apple.com/documentation/devicecheck/validating_apps_that_connect_to_your_server):
+ * CBOR decode, certificate chain validation, nonce check, key extraction,
+ * AAGUID check, and credential ID verification.
+ *
+ * @throws {AttestationError} If any verification step fails.
+ */
 export async function verifyAttestation(appInfo, keyId, challenge, attestation, options) {
     // Decode attestation bytes from base64 if string
     let attestationBytes;

package/esm/src/errors.d.ts

@@ -1,29 +1,52 @@
+/** Error codes returned by {@linkcode AttestationError}. */
 export declare enum AttestationErrorCode {
+    /** CBOR decoding or structural validation failed. */
     INVALID_FORMAT = "INVALID_FORMAT",
+    /** X.509 certificate chain verification failed. */
     INVALID_CERTIFICATE_CHAIN = "INVALID_CERTIFICATE_CHAIN",
+    /** Computed nonce does not match the nonce in the leaf certificate. */
     NONCE_MISMATCH = "NONCE_MISMATCH",
+    /** RP ID hash does not match SHA-256 of the app ID. */
     RP_ID_MISMATCH = "RP_ID_MISMATCH",
+    /** Public key hash does not match the provided key ID. */
     KEY_ID_MISMATCH = "KEY_ID_MISMATCH",
+    /** Sign count is not zero (required for attestation). */
     INVALID_COUNTER = "INVALID_COUNTER",
+    /** AAGUID does not match the expected environment (production/development). */
     INVALID_AAGUID = "INVALID_AAGUID"
 }
+/** Thrown when attestation verification fails. */
 export declare class AttestationError extends Error {
+    /** Machine-readable error code. */
     readonly code: AttestationErrorCode;
     readonly name = "AttestationError";
-    constructor(code: AttestationErrorCode, message: string);
+    constructor(
+    /** Machine-readable error code. */
+    code: AttestationErrorCode, message: string);
 }
+/** Error codes returned by {@linkcode AssertionError}. */
 export declare enum AssertionErrorCode {
+    /** CBOR decoding or structural validation failed. */
     INVALID_FORMAT = "INVALID_FORMAT",
+    /** RP ID hash does not match SHA-256 of the app ID. */
     RP_ID_MISMATCH = "RP_ID_MISMATCH",
+    /** Sign count was not greater than the previously stored value. */
     COUNTER_NOT_INCREMENTED = "COUNTER_NOT_INCREMENTED",
+    /** ECDSA signature verification failed. */
     SIGNATURE_INVALID = "SIGNATURE_INVALID",
+    /** No device key found for the given device ID (used by {@linkcode withAssertion}). */
     DEVICE_NOT_FOUND = "DEVICE_NOT_FOUND",
+    /** An internal or storage callback error occurred (used by {@linkcode withAssertion}). */
     INTERNAL_ERROR = "INTERNAL_ERROR"
 }
+/** Thrown when assertion verification fails. */
 export declare class AssertionError extends Error {
+    /** Machine-readable error code. */
     readonly code: AssertionErrorCode;
     readonly name = "AssertionError";
-    constructor(code: AssertionErrorCode, message: string, options?: {
+    constructor(
+    /** Machine-readable error code. */
+    code: AssertionErrorCode, message: string, options?: {
         cause?: unknown;
     });
 }

package/esm/src/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/src/errors.ts"],"names":[],"mappings":"AAEA,oBAAY,oBAAoB;IAC9B,cAAc,mBAAmB;IACjC,yBAAyB,8BAA8B;IACvD,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,eAAe,oBAAoB;IACnC,cAAc,mBAAmB;CAClC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,IAAI,EAAE,oBAAoB;IAF5C,SAAkB,IAAI,sBAAsB;gBAE1B,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM;CAIlB;AAED,oBAAY,kBAAkB;IAC5B,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC,uBAAuB,4BAA4B;IACnD,iBAAiB,sBAAsB;IACvC,gBAAgB,qBAAqB;IACrC,cAAc,mBAAmB;CAClC;AAED,qBAAa,cAAe,SAAQ,KAAK;aAGrB,IAAI,EAAE,kBAAkB;IAF1C,SAAkB,IAAI,oBAAoB;gBAExB,IAAI,EAAE,kBAAkB,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/src/errors.ts"],"names":[],"mappings":"AAEA,4DAA4D;AAC5D,oBAAY,oBAAoB;IAC9B,qDAAqD;IACrD,cAAc,mBAAmB;IACjC,mDAAmD;IACnD,yBAAyB,8BAA8B;IACvD,uEAAuE;IACvE,cAAc,mBAAmB;IACjC,uDAAuD;IACvD,cAAc,mBAAmB;IACjC,0DAA0D;IAC1D,eAAe,oBAAoB;IACnC,yDAAyD;IACzD,eAAe,oBAAoB;IACnC,+EAA+E;IAC/E,cAAc,mBAAmB;CAClC;AAED,kDAAkD;AAClD,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,mCAAmC;aACnB,IAAI,EAAE,oBAAoB;IAH5C,SAAkB,IAAI,sBAAsB;;IAE1C,mCAAmC;IACnB,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM;CAIlB;AAED,0DAA0D;AAC1D,oBAAY,kBAAkB;IAC5B,qDAAqD;IACrD,cAAc,mBAAmB;IACjC,uDAAuD;IACvD,cAAc,mBAAmB;IACjC,mEAAmE;IACnE,uBAAuB,4BAA4B;IACnD,2CAA2C;IAC3C,iBAAiB,sBAAsB;IACvC,uFAAuF;IACvF,gBAAgB,qBAAqB;IACrC,0FAA0F;IAC1F,cAAc,mBAAmB;CAClC;AAED,gDAAgD;AAChD,qBAAa,cAAe,SAAQ,KAAK;IAGrC,mCAAmC;aACnB,IAAI,EAAE,kBAAkB;IAH1C,SAAkB,IAAI,oBAAoB;;IAExC,mCAAmC;IACnB,IAAI,EAAE,kBAAkB,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC"}

package/esm/src/errors.js

@@ -1,16 +1,27 @@
 // src/errors.ts
+/** Error codes returned by {@linkcode AttestationError}. */
 export var AttestationErrorCode;
 (function (AttestationErrorCode) {
+    /** CBOR decoding or structural validation failed. */
     AttestationErrorCode["INVALID_FORMAT"] = "INVALID_FORMAT";
+    /** X.509 certificate chain verification failed. */
     AttestationErrorCode["INVALID_CERTIFICATE_CHAIN"] = "INVALID_CERTIFICATE_CHAIN";
+    /** Computed nonce does not match the nonce in the leaf certificate. */
     AttestationErrorCode["NONCE_MISMATCH"] = "NONCE_MISMATCH";
+    /** RP ID hash does not match SHA-256 of the app ID. */
     AttestationErrorCode["RP_ID_MISMATCH"] = "RP_ID_MISMATCH";
+    /** Public key hash does not match the provided key ID. */
     AttestationErrorCode["KEY_ID_MISMATCH"] = "KEY_ID_MISMATCH";
+    /** Sign count is not zero (required for attestation). */
     AttestationErrorCode["INVALID_COUNTER"] = "INVALID_COUNTER";
+    /** AAGUID does not match the expected environment (production/development). */
     AttestationErrorCode["INVALID_AAGUID"] = "INVALID_AAGUID";
 })(AttestationErrorCode || (AttestationErrorCode = {}));
+/** Thrown when attestation verification fails. */
 export class AttestationError extends Error {
-    constructor(code, message) {
+    constructor(
+    /** Machine-readable error code. */
+    code, message) {
         super(message);
         Object.defineProperty(this, "code", {
             enumerable: true,
@@ -26,17 +37,27 @@ export class AttestationError extends Error {
         });
     }
 }
+/** Error codes returned by {@linkcode AssertionError}. */
 export var AssertionErrorCode;
 (function (AssertionErrorCode) {
+    /** CBOR decoding or structural validation failed. */
     AssertionErrorCode["INVALID_FORMAT"] = "INVALID_FORMAT";
+    /** RP ID hash does not match SHA-256 of the app ID. */
     AssertionErrorCode["RP_ID_MISMATCH"] = "RP_ID_MISMATCH";
+    /** Sign count was not greater than the previously stored value. */
     AssertionErrorCode["COUNTER_NOT_INCREMENTED"] = "COUNTER_NOT_INCREMENTED";
+    /** ECDSA signature verification failed. */
     AssertionErrorCode["SIGNATURE_INVALID"] = "SIGNATURE_INVALID";
+    /** No device key found for the given device ID (used by {@linkcode withAssertion}). */
     AssertionErrorCode["DEVICE_NOT_FOUND"] = "DEVICE_NOT_FOUND";
+    /** An internal or storage callback error occurred (used by {@linkcode withAssertion}). */
     AssertionErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
 })(AssertionErrorCode || (AssertionErrorCode = {}));
+/** Thrown when assertion verification fails. */
 export class AssertionError extends Error {
-    constructor(code, message, options) {
+    constructor(
+    /** Machine-readable error code. */
+    code, message, options) {
         super(message, options);
         Object.defineProperty(this, "code", {
             enumerable: true,

package/esm/src/with-assertion.d.ts

@@ -1,27 +1,51 @@
 import { AssertionError } from "./errors.js";
+/** Default HTTP header name for the base64-encoded assertion. */
 export declare const DEFAULT_ASSERTION_HEADER = "X-App-Attest-Assertion";
+/** Default HTTP header name for the device identifier. */
 export declare const DEFAULT_DEVICE_ID_HEADER = "X-App-Attest-Device-Id";
+/** Stored device key material returned by the `getDeviceKey` callback. */
 export type DeviceKey = {
+    /** PEM-encoded ECDSA P-256 public key from attestation. */
     publicKeyPem: string;
+    /** Last verified sign count for this device. */
     signCount: number;
 };
+/** Context passed to the inner handler after successful assertion verification. */
 export type AssertionContext = {
+    /** Device identifier from the request. */
     deviceId: string;
+    /** Updated sign count after verification. */
     signCount: number;
+    /** Raw request body bytes (the client data that was signed). */
     rawBody: Uint8Array;
 };
+/** Custom function to extract assertion data from an incoming request. */
 export type ExtractAssertionFn = (req: Request) => Promise<{
     assertion: string;
     deviceId: string;
     clientData: Uint8Array;
 }>;
+/** Configuration for the {@linkcode withAssertion} middleware. */
 export type WithAssertionOptions = {
+    /** Apple App ID in the format `TEAMID.bundleId`. */
     appId: string;
+    /** Set to `true` for development environment attestations. */
     developmentEnv?: boolean;
+    /** Retrieve the stored device key for a given device ID. Return `null` if not found. */
     getDeviceKey: (deviceId: string) => Promise<DeviceKey | null>;
+    /** Persist the new sign count after successful verification. */
     updateSignCount: (deviceId: string, newSignCount: number) => Promise<void>;
+    /** Override the default header-based assertion extraction. */
     extractAssertion?: ExtractAssertionFn;
+    /** Custom error response handler. Defaults to JSON error responses. */
     onError?: (error: AssertionError, req: Request) => Response | Promise<Response>;
 };
+/**
+ * Request handler middleware that verifies App Attest assertions.
+ *
+ * Wraps a handler function with automatic assertion verification,
+ * device key lookup, and sign count management. Returns a new handler
+ * that rejects unauthenticated requests with appropriate HTTP error responses.
+ */
 export declare function withAssertion(options: WithAssertionOptions, handler: (req: Request, context: AssertionContext) => Response | Promise<Response>): (req: Request) => Promise<Response>;
 //# sourceMappingURL=with-assertion.d.ts.map

package/esm/src/with-assertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-assertion.d.ts","sourceRoot":"","sources":["../../src/src/with-assertion.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC;AAEjE,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AACjE,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAEjE,MAAM,MAAM,SAAS,GAAG;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC9D,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IACtC,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,OAAO,KACT,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnC,CAAC;AAmCF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,gBAAgB,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAChC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuErC"}
+{"version":3,"file":"with-assertion.d.ts","sourceRoot":"","sources":["../../src/src/with-assertion.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC;AAEjE,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AACjE,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAEjE,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG;IACtB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG;IACjC,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC9D,gEAAgE;IAChE,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IACtC,uEAAuE;IACvE,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,OAAO,KACT,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnC,CAAC;AAmCF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,CACP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,gBAAgB,KACtB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAChC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuErC"}

package/esm/src/with-assertion.js

@@ -1,7 +1,9 @@
 // src/with-assertion.ts
 import { verifyAssertion } from "./assertion.js";
 import { AssertionError, AssertionErrorCode } from "./errors.js";
+/** Default HTTP header name for the base64-encoded assertion. */
 export const DEFAULT_ASSERTION_HEADER = "X-App-Attest-Assertion";
+/** Default HTTP header name for the device identifier. */
 export const DEFAULT_DEVICE_ID_HEADER = "X-App-Attest-Device-Id";
 async function defaultExtractAssertion(req) {
     const assertion = req.headers.get(DEFAULT_ASSERTION_HEADER);
@@ -20,6 +22,13 @@ function defaultErrorResponse(error) {
             : 401;
     return new Response(JSON.stringify({ error: error.message, code: error.code }), { status, headers: { "Content-Type": "application/json" } });
 }
+/**
+ * Request handler middleware that verifies App Attest assertions.
+ *
+ * Wraps a handler function with automatic assertion verification,
+ * device key lookup, and sign count management. Returns a new handler
+ * that rejects unauthenticated requests with appropriate HTTP error responses.
+ */
 export function withAssertion(options, handler) {
     const appInfo = {
         appId: options.appId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bradford-tech/supabase-integrity-attest",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Verify Apple App Attest attestations and assertions using WebCrypto.",
   "repository": {
     "type": "git",