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

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,7 +1,28 @@
+/**
+ * Lightweight assertion-only entry point. Avoids pulling in `asn1js` and
+ * `@noble/curves`, keeping the bundle minimal for assertion-only use cases.
+ *
+ * ```ts
+ * import {
+ *   verifyAssertion,
+ *   withAssertion,
+ * } 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";
 export { withAssertion } from "./src/with-assertion.js";
 export { DEFAULT_ASSERTION_HEADER, DEFAULT_DEVICE_ID_HEADER, } from "./src/with-assertion.js";
-export type { AssertionContext, DeviceKey, ExtractAssertionFn, WithAssertionOptions, } from "./src/with-assertion.js";
+export type { AssertionContext, AssertionTimings, DeviceKey, ExtractAssertionFn, WithAssertionOptions, } from "./src/with-assertion.js";
 //# sourceMappingURL=assertion.d.ts.map

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;;;;;;;;;;;;;;;;;;;;GAoBG;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,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC"}

package/esm/assertion.js

@@ -1,6 +1,26 @@
-// 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,
+ *   withAssertion,
+ * } 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
+// withAssertion middleware
 export { withAssertion } from "./src/with-assertion.js";
 export { DEFAULT_ASSERTION_HEADER, DEFAULT_DEVICE_ID_HEADER, } from "./src/with-assertion.js";

package/esm/attestation.d.ts

@@ -1,4 +1,26 @@
+/**
+ * Full attestation entry point including certificate chain verification
+ * dependencies (`asn1js`, `@noble/curves`).
+ *
+ * ```ts
+ * import {
+ *   verifyAttestation,
+ *   withAttestation,
+ * } 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";
+export { withAttestation } from "./src/with-attestation.js";
+export type { AttestationContext, AttestationTimings, ExtractAttestationFn, WithAttestationOptions, } from "./src/with-attestation.js";
 //# sourceMappingURL=attestation.d.ts.map

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;;;;;;;;;;;;;;;;;;;GAmBG;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;AAGzE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC"}

package/esm/attestation.js

@@ -1,3 +1,24 @@
-// 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,
+ *   withAttestation,
+ * } 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";
+// withAttestation middleware
+export { withAttestation } from "./src/with-attestation.js";

package/esm/mod.d.ts

@@ -1,3 +1,93 @@
+/**
+ * Verify Apple App Attest attestations and assertions using WebCrypto.
+ *
+ * This library implements Apple's full
+ * [App Attest](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity)
+ * server-side verification — CBOR decoding, X.509 certificate chain
+ * validation, nonce verification, ECDSA signature checks — using only
+ * WebCrypto APIs so it runs in Supabase Edge Functions, Deno Deploy,
+ * and other edge runtimes with no native dependencies.
+ *
+ * ## Attestation
+ *
+ * Verify a new device and extract its public key:
+ *
+ * ```ts
+ * import { verifyAttestation } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const { publicKeyPem, receipt, signCount } = await verifyAttestation(
+ *   { appId: "TEAMID.com.example.app" },
+ *   keyId,
+ *   challenge,
+ *   attestation,
+ * );
+ * // Store publicKeyPem and signCount for future assertion verification
+ * ```
+ *
+ * ## Assertion
+ *
+ * Verify ongoing requests from an already-attested device:
+ *
+ * ```ts
+ * import { verifyAssertion } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const { signCount } = await verifyAssertion(
+ *   { appId: "TEAMID.com.example.app" },
+ *   assertion,
+ *   clientData,
+ *   publicKeyPem,
+ *   previousSignCount,
+ * );
+ * // Persist the updated signCount
+ * ```
+ *
+ * ## Middleware
+ *
+ * Use the {@linkcode withAttestation} and {@linkcode withAssertion}
+ * wrappers for automatic verification, callback-driven storage, and
+ * typed error handling:
+ *
+ * ```ts
+ * import {
+ *   withAttestation,
+ *   withAssertion,
+ * } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const attestHandler = withAttestation(
+ *   {
+ *     appId: "TEAMID.com.example.app",
+ *     consumeChallenge,
+ *     storeDeviceKey,
+ *   },
+ *   (_req, ctx) =>
+ *     Response.json({ ok: true, deviceId: ctx.deviceId }),
+ * );
+ *
+ * const protectedHandler = withAssertion(
+ *   {
+ *     appId: "TEAMID.com.example.app",
+ *     getDeviceKey,
+ *     commitSignCount,
+ *   },
+ *   (_req, ctx) =>
+ *     Response.json({ hello: ctx.deviceId, counter: ctx.signCount }),
+ * );
+ * ```
+ *
+ * ## Subpath imports
+ *
+ * For smaller bundles, import only what you need:
+ *
+ * - `@bradford-tech/supabase-integrity-attest/attestation` — attestation
+ *   (`verifyAttestation`, `withAttestation`). Full crypto deps.
+ * - `@bradford-tech/supabase-integrity-attest/assertion` — assertion
+ *   (`verifyAssertion`, `withAssertion`). Excludes `asn1js` and
+ *   `@noble/curves` to keep the bundle minimal.
+ *
+ * Full documentation: {@link https://integrity-attest.bradford.tech}
+ *
+ * @module
+ */
 export type { AppInfo, AttestationResult, VerifyAttestationOptions, } from "./src/attestation.js";
 export type { AssertionResult } from "./src/assertion.js";
 export { verifyAttestation } from "./src/attestation.js";
@@ -5,5 +95,7 @@ export { verifyAssertion } from "./src/assertion.js";
 export { AssertionError, AssertionErrorCode, AttestationError, AttestationErrorCode, } from "./src/errors.js";
 export { withAssertion } from "./src/with-assertion.js";
 export { DEFAULT_ASSERTION_HEADER, DEFAULT_DEVICE_ID_HEADER, } from "./src/with-assertion.js";
-export type { AssertionContext, DeviceKey, ExtractAssertionFn, WithAssertionOptions, } from "./src/with-assertion.js";
+export type { AssertionContext, AssertionTimings, DeviceKey, ExtractAssertionFn, WithAssertionOptions, } from "./src/with-assertion.js";
+export { withAttestation } from "./src/with-attestation.js";
+export type { AttestationContext, AttestationTimings, ExtractAttestationFn, WithAttestationOptions, } from "./src/with-attestation.js";
 //# sourceMappingURL=mod.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;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,gBAAgB,EAChB,SAAS,EACT,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC"}

package/esm/mod.js

@@ -1,7 +1,98 @@
-// mod.ts — public API surface
+/**
+ * Verify Apple App Attest attestations and assertions using WebCrypto.
+ *
+ * This library implements Apple's full
+ * [App Attest](https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity)
+ * server-side verification — CBOR decoding, X.509 certificate chain
+ * validation, nonce verification, ECDSA signature checks — using only
+ * WebCrypto APIs so it runs in Supabase Edge Functions, Deno Deploy,
+ * and other edge runtimes with no native dependencies.
+ *
+ * ## Attestation
+ *
+ * Verify a new device and extract its public key:
+ *
+ * ```ts
+ * import { verifyAttestation } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const { publicKeyPem, receipt, signCount } = await verifyAttestation(
+ *   { appId: "TEAMID.com.example.app" },
+ *   keyId,
+ *   challenge,
+ *   attestation,
+ * );
+ * // Store publicKeyPem and signCount for future assertion verification
+ * ```
+ *
+ * ## Assertion
+ *
+ * Verify ongoing requests from an already-attested device:
+ *
+ * ```ts
+ * import { verifyAssertion } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const { signCount } = await verifyAssertion(
+ *   { appId: "TEAMID.com.example.app" },
+ *   assertion,
+ *   clientData,
+ *   publicKeyPem,
+ *   previousSignCount,
+ * );
+ * // Persist the updated signCount
+ * ```
+ *
+ * ## Middleware
+ *
+ * Use the {@linkcode withAttestation} and {@linkcode withAssertion}
+ * wrappers for automatic verification, callback-driven storage, and
+ * typed error handling:
+ *
+ * ```ts
+ * import {
+ *   withAttestation,
+ *   withAssertion,
+ * } from "@bradford-tech/supabase-integrity-attest";
+ *
+ * const attestHandler = withAttestation(
+ *   {
+ *     appId: "TEAMID.com.example.app",
+ *     consumeChallenge,
+ *     storeDeviceKey,
+ *   },
+ *   (_req, ctx) =>
+ *     Response.json({ ok: true, deviceId: ctx.deviceId }),
+ * );
+ *
+ * const protectedHandler = withAssertion(
+ *   {
+ *     appId: "TEAMID.com.example.app",
+ *     getDeviceKey,
+ *     commitSignCount,
+ *   },
+ *   (_req, ctx) =>
+ *     Response.json({ hello: ctx.deviceId, counter: ctx.signCount }),
+ * );
+ * ```
+ *
+ * ## Subpath imports
+ *
+ * For smaller bundles, import only what you need:
+ *
+ * - `@bradford-tech/supabase-integrity-attest/attestation` — attestation
+ *   (`verifyAttestation`, `withAttestation`). Full crypto deps.
+ * - `@bradford-tech/supabase-integrity-attest/assertion` — assertion
+ *   (`verifyAssertion`, `withAssertion`). Excludes `asn1js` and
+ *   `@noble/curves` to keep the bundle minimal.
+ *
+ * Full documentation: {@link https://integrity-attest.bradford.tech}
+ *
+ * @module
+ */
 export { verifyAttestation } from "./src/attestation.js";
 export { verifyAssertion } from "./src/assertion.js";
 export { AssertionError, AssertionErrorCode, AttestationError, AttestationErrorCode, } from "./src/errors.js";
-// withAssertion wrapper
+// withAssertion middleware
 export { withAssertion } from "./src/with-assertion.js";
 export { DEFAULT_ASSERTION_HEADER, DEFAULT_DEVICE_ID_HEADER, } from "./src/with-assertion.js";
+// withAttestation middleware
+export { withAttestation } from "./src/with-attestation.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,77 @@
+/** 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",
-    INVALID_AAGUID = "INVALID_AAGUID"
+    /** AAGUID does not match the expected environment (production/development). */
+    INVALID_AAGUID = "INVALID_AAGUID",
+    /**
+     * The `consumeChallenge` callback returned `false`, meaning the challenge
+     * was missing, expired, or already consumed. Used by {@linkcode withAttestation}.
+     */
+    CHALLENGE_INVALID = "CHALLENGE_INVALID",
+    /**
+     * An internal or storage callback error occurred (used by
+     * {@linkcode withAttestation}). The original error is attached via
+     * `Error.cause` and is deliberately NOT reflected in the HTTP response
+     * body to avoid leaking database schema or driver diagnostics.
+     */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
 }
+/** Thrown when attestation verification fails. */
 export declare class AttestationError extends Error {
+    /** Machine-readable error code. */
     readonly code: AttestationErrorCode;
+    /** Discriminant for `instanceof` checks in catch blocks. Always `"AttestationError"`. */
     readonly name = "AttestationError";
-    constructor(code: AttestationErrorCode, message: string);
+    /** Create an AttestationError with a machine-readable code and human-readable message. */
+    constructor(
+    /** Machine-readable error code. */
+    code: AttestationErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
 }
+/** 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",
-    INTERNAL_ERROR = "INTERNAL_ERROR"
+    /** An internal or storage callback error occurred (used by {@linkcode withAssertion}). */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /**
+     * The `commitSignCount` callback returned `false`, meaning another
+     * concurrent request already advanced the stored counter past this value.
+     * Indicates an expected race under concurrent load, not a client bug.
+     * Used by {@linkcode withAssertion}.
+     */
+    SIGN_COUNT_STALE = "SIGN_COUNT_STALE"
 }
+/** Thrown when assertion verification fails. */
 export declare class AssertionError extends Error {
+    /** Machine-readable error code. */
     readonly code: AssertionErrorCode;
+    /** Discriminant for `instanceof` checks in catch blocks. Always `"AssertionError"`. */
     readonly name = "AssertionError";
-    constructor(code: AssertionErrorCode, message: string, options?: {
+    /** Create an AssertionError with a machine-readable code and human-readable message. */
+    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;IACjC;;;OAGG;IACH,iBAAiB,sBAAsB;IACvC;;;;;OAKG;IACH,cAAc,mBAAmB;CAClC;AAED,kDAAkD;AAClD,qBAAa,gBAAiB,SAAQ,KAAK;IAKvC,mCAAmC;aACnB,IAAI,EAAE,oBAAoB;IAL5C,yFAAyF;IACzF,SAAkB,IAAI,sBAAsB;IAC5C,0FAA0F;;IAExF,mCAAmC;IACnB,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;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;IACjC;;;;;OAKG;IACH,gBAAgB,qBAAqB;CACtC;AAED,gDAAgD;AAChD,qBAAa,cAAe,SAAQ,KAAK;IAKrC,mCAAmC;aACnB,IAAI,EAAE,kBAAkB;IAL1C,uFAAuF;IACvF,SAAkB,IAAI,oBAAoB;IAC1C,wFAAwF;;IAEtF,mCAAmC;IACnB,IAAI,EAAE,kBAAkB,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC"}