@motebit/crypto-appattest 1.0.0

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * @motebit/crypto-appattest — Apple App Attest chain-verification
+ * adapter for motebit hardware-attestation claims.
+ *
+ * The metabolic leaf `@motebit/crypto` delegates to when a
+ * `HardwareAttestationClaim` declares `platform: "device_check"`.
+ * Dep-thin `@motebit/crypto` stays permissive-floor-pure; this package,
+ * also on the permissive floor (Apache-2.0), metabolizes `@peculiar/x509`
+ * + `cbor2` to judge whether Apple's published CA rooted the leaf that
+ * signed the caller's attestation.
+ *
+ * Wiring from a consumer:
+ *
+ * ```ts
+ * import { verify } from "@motebit/crypto";
+ * import { deviceCheckVerifier } from "@motebit/crypto-appattest";
+ *
+ * const result = await verify(credential, {
+ *   hardwareAttestation: { deviceCheck: deviceCheckVerifier({ expectedBundleId: "com.motebit.app" }) },
+ * });
+ * ```
+ *
+ * This package exports no global state, no side-effect registrations;
+ * the injection is call-site only.
+ */
+import { verifyAppAttestReceipt } from "./verify.js";
+export { parseAppAttestCbor } from "./cbor.js";
+export { APPLE_APPATTEST_ROOT_PEM, APPLE_APPATTEST_FMT } from "./apple-root.js";
+export { verifyAppAttestReceipt } from "./verify.js";
+/**
+ * Factory — build a `deviceCheck` verifier bound to a specific bundle
+ * and (optionally) a test root / clock / fmt. The returned function
+ * matches the `HardwareAttestationVerifiers.deviceCheck` signature the
+ * `@motebit/crypto` dispatcher expects.
+ *
+ * Signature widened 2026-04-22: the third `context` parameter carries
+ * the motebit_id / device_id / attested_at fields the VC subject
+ * declares so the verifier can re-derive the JCS body Apple signed
+ * over and cryptographically bind it to the caller's Ed25519 identity
+ * (see `verify.ts` step 6). Pre-existing call sites that pass only
+ * `(claim, expectedIdentityHex)` still compile — the context is
+ * optional — but they lose the identity-binding channel and receive
+ * `identity_bound: false` in the result.
+ *
+ * Kept as a factory rather than a free function so the consumer's
+ * bundle ID is captured once at wiring time, not repeated at every
+ * call site — every subsequent `verify()` call inherits the same
+ * binding.
+ */
+export function deviceCheckVerifier(config) {
+    return async (claim, expectedIdentityHex, context) => {
+        const opts = {
+            expectedBundleId: config.expectedBundleId,
+            expectedIdentityPublicKeyHex: expectedIdentityHex,
+            ...(config.rootPem !== undefined ? { rootPem: config.rootPem } : {}),
+            ...(config.now !== undefined ? { now: config.now } : {}),
+            ...(config.expectedFmt !== undefined ? { expectedFmt: config.expectedFmt } : {}),
+            ...(context?.expectedMotebitId !== undefined
+                ? { expectedMotebitId: context.expectedMotebitId }
+                : {}),
+            ...(context?.expectedDeviceId !== undefined
+                ? { expectedDeviceId: context.expectedDeviceId }
+                : {}),
+            ...(context?.expectedAttestedAt !== undefined
+                ? { expectedAttestedAt: context.expectedAttestedAt }
+                : {}),
+        };
+        const detail = await verifyAppAttestReceipt(claim, opts);
+        return {
+            valid: detail.valid,
+            platform: "device_check",
+            errors: detail.errors,
+            attestation_detail: detail,
+        };
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAgDrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAiC;IAMjC,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,EAAE;QACnD,MAAM,IAAI,GAA2B;YACnC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,4BAA4B,EAAE,mBAAmB;YACjD,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChF,GAAG,CAAC,OAAO,EAAE,iBAAiB,KAAK,SAAS;gBAC1C,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE;gBAClD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,SAAS;gBACzC,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE;gBAChD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,SAAS;gBAC3C,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACzD,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,QAAQ,EAAE,cAAc;YACxB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,kBAAkB,EAAE,MAAM;SAC3B,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,109 @@
+/**
+ * App Attest receipt verifier — the core judgment function this
+ * package exports.
+ *
+ * Flow (matches Apple's published verification recipe for App Attest,
+ * plus the motebit-specific identity-key binding step):
+ *
+ *   1. Split the receipt into (attestationObjectBase64,
+ *      keyIdBase64, clientDataHashBase64).
+ *   2. CBOR-decode the attestation object to {fmt, attStmt:{x5c,
+ *      receipt}, authData}. Assert fmt === "apple-appattest".
+ *   3. Parse leaf + intermediate as X.509. Walk the chain from leaf to
+ *      a self-signed root and verify every signature, every CA bit,
+ *      every validity window. The terminal cert's DER must equal the
+ *      pinned Apple App Attest root.
+ *   4. Extract OID `1.2.840.113635.100.8.2` from the leaf's
+ *      extensions. Assert its payload equals SHA256(authData ||
+ *      clientDataHash) where clientDataHash is the transmitted hash.
+ *      (In App Attest parlance: the "nonce" binding.)
+ *   5. Parse authData (WebAuthn format). First 32 bytes is
+ *      `rpIdHash`; assert it equals SHA256(bundleId). (The "bundle"
+ *      binding.)
+ *   6. Reconstruct the JCS-canonical attestation body from
+ *      (motebit_id, device_id, identity_public_key, attested_at) the
+ *      caller supplies, SHA-256 it, and byte-compare against the
+ *      transmitted `clientDataHash`. This is the cross-stack binding
+ *      — without it, every other step would prove only that *some*
+ *      Apple-attested iOS device did something, not that the Ed25519
+ *      key the credential subject claims is actually on that device.
+ *
+ * Apple's own inner `receipt` field is NOT verified here — that
+ * requires Apple's server-side refresh endpoint and is out of scope
+ * for v1. The outer chain + nonce binding + bundle binding + motebit
+ * identity binding is enough for third-party self-verification of
+ * device-attested identity.
+ */
+import type { HardwareAttestationClaim } from "@motebit/protocol";
+export interface AppAttestVerifyOptions {
+    /** iOS bundle identifier that minted the attestation (e.g. "com.motebit.app"). */
+    readonly expectedBundleId: string;
+    /**
+     * Ed25519 identity key (lowercase hex) the motebit VC claims. The
+     * attested body MUST name this key.
+     */
+    readonly expectedIdentityPublicKeyHex: string;
+    /**
+     * motebit_id from the credential subject. Part of the canonical
+     * attestation body the Swift mint path signs; re-derived here and
+     * byte-compared against the transmitted clientDataHash so a
+     * malicious native client cannot substitute a different body.
+     */
+    readonly expectedMotebitId?: string;
+    /**
+     * device_id from the credential subject. Same binding role as
+     * `expectedMotebitId`.
+     */
+    readonly expectedDeviceId?: string;
+    /**
+     * `attested_at` (unix ms) from the credential subject. Same binding
+     * role as `expectedMotebitId`.
+     */
+    readonly expectedAttestedAt?: number;
+    /**
+     * Override the pinned Apple root — tests fabricate their own root so
+     * chain verification exercises the same code path without needing
+     * real Apple-signed leaves. Defaults to the pinned
+     * `APPLE_APPATTEST_ROOT_PEM`.
+     */
+    readonly rootPem?: string;
+    /**
+     * Clock for chain-validity checks. Defaults to `Date.now`. Tests inject
+     * a fixed clock to keep certificate validity windows deterministic.
+     */
+    readonly now?: () => number;
+    /**
+     * Override the attestation format check. Defaults to `"apple-appattest"`
+     * — the value Apple emits. Exposed only so test fabrications that
+     * exercise chain-validation edge cases can still reach the code path.
+     */
+    readonly expectedFmt?: string;
+}
+export interface AppAttestVerifyError {
+    readonly message: string;
+}
+export interface AppAttestVerifyResult {
+    readonly valid: boolean;
+    readonly cert_chain_valid: boolean;
+    readonly nonce_bound: boolean;
+    readonly bundle_bound: boolean;
+    readonly identity_bound: boolean;
+    readonly errors: readonly AppAttestVerifyError[];
+}
+/**
+ * Apple App Attest attestation verifier.
+ *
+ * Pure. No network. No filesystem. Deterministic given `now()`.
+ *
+ * `claim` is the `HardwareAttestationClaim` as carried inside the
+ * motebit AgentTrustCredential. For App Attest, the
+ * `attestation_receipt` field is expected to be three base64url
+ * segments separated by `.`:
+ *
+ *   `{attestationObjectB64}.{keyIdB64}.{clientDataHashB64}`
+ *
+ * The mobile mint path constructs this shape; see
+ * `apps/mobile/src/mint-hardware-credential.ts`.
+ */
+export declare function verifyAppAttestReceipt(claim: HardwareAttestationClaim, opts: AppAttestVerifyOptions): Promise<AppAttestVerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAKlE,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,4BAA4B,EAAE,MAAM,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,wBAAwB,EAC/B,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,qBAAqB,CAAC,CAqMhC"}