@learncard/sss-key-manager 0.2.0 → 0.2.2

package/src/escrow-nitro-attestation.test.ts

@@ -0,0 +1,276 @@
+// @vitest-environment node
+import { readFileSync, readdirSync } from 'node:fs';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { decode, encode } from 'cborg';
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import { NitroAttestationError, verifyNitroAttestationDocument } from './escrow-nitro-attestation';
+import { verifyEnclaveAttestation } from './escrow-attestation';
+import manifest from './__fixtures__/nitro-attestation/manifest.json';
+import type { EscrowAttestationPolicy } from './types';
+
+const directory = new URL('./__fixtures__/nitro-attestation/', import.meta.url);
+const fixture = (name: string): string =>
+    readFileSync(new URL(`${name}.cbor.b64`, directory), 'utf8').trim();
+const nonce = Uint8Array.from(manifest.nonceHex.match(/../g)!, byte => parseInt(byte, 16));
+const measurement = { pcr0: manifest.pcrs[0], pcr1: manifest.pcrs[1], pcr2: manifest.pcrs[2] };
+const policy: Extract<EscrowAttestationPolicy, { mode: 'nitro' }> = {
+    mode: 'nitro',
+    pinnedMeasurements: [measurement],
+    rootCertificateSha256: manifest.rootSha256,
+};
+const options = { expectedNonce: nonce, policy, now: manifest.nowMs };
+const reasonMap: Record<string, string> = {
+    'debug PCRs': 'debug',
+    'missing intermediate': 'chain',
+    'root pin': 'root',
+};
+
+describe('FakeNsm Nitro attestation', () => {
+    afterEach(() => vi.restoreAllMocks());
+    it('covers every committed document fixture', () => {
+        expect(
+            readdirSync(directory)
+                .filter(file => file.endsWith('.cbor.b64'))
+                .sort()
+        ).toEqual(
+            Object.keys(manifest.cases)
+                .map(name => `${name}.cbor.b64`)
+                .sort()
+        );
+    });
+    for (const [name, testCase] of Object.entries(manifest.cases)) {
+        it(name, async () => {
+            const expectedNonce =
+                'nonceHex' in testCase
+                    ? Uint8Array.from(testCase.nonceHex.match(/../g)!, byte => parseInt(byte, 16))
+                    : nonce;
+            const result = verifyNitroAttestationDocument(fixture(name), {
+                ...options,
+                expectedNonce,
+            });
+            if (testCase.accept) {
+                await expect(result).resolves.toMatchObject({
+                    escrowPublicKeySpkiB64: manifest.userDataBase64,
+                    timestamp: manifest.timestamp,
+                    pcrs: manifest.pcrs,
+                    previousKeyIds:
+                        'previousKeyIds' in testCase
+                            ? testCase.previousKeyIds
+                            : manifest.previousKeyIds,
+                });
+            } else if ('reason' in testCase) {
+                await expect(result).rejects.toMatchObject({
+                    name: 'NitroAttestationError',
+                    reason: reasonMap[testCase.reason] ?? testCase.reason,
+                });
+            }
+        });
+    }
+    it('accepts an optional outer tag 18', async () => {
+        const tagged = new Uint8Array([0xd2, ...base64ToBuffer(fixture('valid'))]);
+        await expect(
+            verifyNitroAttestationDocument(bufferToBase64(tagged.buffer), options)
+        ).resolves.toBeDefined();
+    });
+    it('rejects cross-combinations of pinned tuples', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: {
+                    ...policy,
+                    pinnedMeasurements: [
+                        { ...measurement, pcr1: 'ff'.repeat(48) },
+                        { ...measurement, pcr0: 'ff'.repeat(48) },
+                    ],
+                },
+            })
+        ).rejects.toMatchObject({ reason: 'pcr' });
+    });
+    it('rejects legacy image-only pins', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: {
+                    ...policy,
+                    pinnedMeasurements: [{ imageSha384: measurement.pcr0 }],
+                },
+            })
+        ).rejects.toMatchObject({ reason: 'pcr' });
+    });
+    it('rejects unknown algorithms before signature verification', async () => {
+        const cose: unknown[] = decode(base64ToBuffer(fixture('valid')), { useMaps: true });
+        cose[0] = encode(new Map([[1, -7]]));
+        await expect(
+            verifyNitroAttestationDocument(
+                bufferToBase64(new Uint8Array(encode(cose)).buffer),
+                options
+            )
+        ).rejects.toMatchObject({ reason: 'alg' });
+    });
+    it('rejects the fake root under the default AWS pin', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: {
+                    mode: 'nitro',
+                    pinnedMeasurements: [measurement],
+                },
+            })
+        ).rejects.toMatchObject({ reason: 'root' });
+    });
+    it('enforces clock skew and configurable freshness', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                now: manifest.timestamp - 60001,
+            })
+        ).rejects.toMatchObject({ reason: 'freshness' });
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: { ...policy, maxAgeMs: 999 },
+            })
+        ).rejects.toMatchObject({ reason: 'freshness' });
+    });
+    it('returns typed CBOR errors', async () => {
+        await expect(verifyNitroAttestationDocument('bad!', options)).rejects.toBeInstanceOf(
+            NitroAttestationError
+        );
+        await expect(verifyNitroAttestationDocument('bad!', options)).rejects.toMatchObject({
+            reason: 'cbor',
+        });
+    });
+    it('binds the wrapper public key to user_data, ignoring unsigned measurements', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(manifest.nowMs);
+        const attestation = {
+            mode: 'nitro',
+            keyId: manifest.keyId,
+            previousKeyIds: manifest.previousKeyIds,
+            publicKey: manifest.userDataBase64,
+            document: fixture('valid'),
+            measurements: { pcr0: 'untrusted' },
+            issuedAt: new Date(manifest.nowMs).toISOString(),
+        };
+        await expect(verifyEnclaveAttestation(attestation, policy, nonce)).resolves.toEqual({
+            mode: 'nitro',
+            keyId: manifest.keyId,
+            previousKeyIds: manifest.previousKeyIds,
+            publicKey: manifest.userDataBase64,
+        });
+        await expect(
+            verifyEnclaveAttestation({ ...attestation, publicKey: 'e30=' }, policy, nonce)
+        ).rejects.toMatchObject({ reason: 'user-data' });
+        await expect(verifyEnclaveAttestation(attestation, policy)).rejects.toMatchObject({
+            reason: 'nonce',
+        });
+    });
+    // P9.2: the plaintext wire `keyId` — what a client actually seals new
+    // envelopes to — must exactly match what is bound inside the signed
+    // document; a divergent (tampered, or simply stale) plaintext keyId is
+    // rejected the same way a wrong public key is.
+    it('rejects a keyId that diverges from the signed document', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(manifest.nowMs);
+        const attestation = {
+            mode: 'nitro',
+            keyId: 'not-the-attested-key',
+            previousKeyIds: manifest.previousKeyIds,
+            publicKey: manifest.userDataBase64,
+            document: fixture('valid'),
+            measurements: {},
+            issuedAt: new Date(manifest.nowMs).toISOString(),
+        };
+        await expect(verifyEnclaveAttestation(attestation, policy, nonce)).rejects.toMatchObject({
+            reason: 'user-data',
+        });
+    });
+    // P9.2: the plaintext wire field must exactly match what is bound inside
+    // the signed document — a divergent (tampered, or simply stale) plaintext
+    // previousKeyIds is rejected the same way a wrong public key is.
+    it('rejects a previousKeyIds that diverges from the signed document', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(manifest.nowMs);
+        const attestation = {
+            mode: 'nitro',
+            keyId: manifest.keyId,
+            previousKeyIds: ['not-the-attested-list'],
+            publicKey: manifest.userDataBase64,
+            document: fixture('valid'),
+            measurements: {},
+            issuedAt: new Date(manifest.nowMs).toISOString(),
+        };
+        await expect(verifyEnclaveAttestation(attestation, policy, nonce)).rejects.toMatchObject({
+            reason: 'user-data',
+        });
+    });
+});
+
+describe('real AWS Nitro attestation', () => {
+    const real = JSON.parse(
+        readFileSync(
+            new URL(
+                './__fixtures__/nitro-attestation-real/staging-nsm-document.json',
+                import.meta.url
+            ),
+            'utf8'
+        )
+    ) as {
+        nonceHex: string;
+        timestamp: number;
+        keyId: string;
+        measurements: { pcr0: string; pcr1: string; pcr2: string };
+        escrowPublicKeySpkiB64: string;
+        measurementHash: string;
+        document: string;
+    };
+    const realNonce = Uint8Array.from(real.nonceHex.match(/../g)!, byte => parseInt(byte, 16));
+    const realOptions = {
+        expectedNonce: realNonce,
+        policy: { mode: 'nitro' as const, pinnedMeasurements: [real.measurements] },
+        now: real.timestamp,
+    };
+
+    it('uses the indefinite-length payload map the NSM actually emits', () => {
+        const cose = decode(base64ToBuffer(real.document), { useMaps: true }) as unknown[];
+        expect((cose[2] as Uint8Array)[0]).toBe(0xbf);
+    });
+
+    it('verifies against the default AWS root, nonce and pinned measurements', async () => {
+        await expect(
+            verifyNitroAttestationDocument(real.document, realOptions)
+        ).resolves.toMatchObject({
+            keyId: real.keyId,
+            escrowPublicKeySpkiB64: real.escrowPublicKeySpkiB64,
+            measurementHash: real.measurementHash,
+            timestamp: real.timestamp,
+        });
+    });
+
+    it('still rejects a real document with a different nonce or unpinned measurements', async () => {
+        await expect(
+            verifyNitroAttestationDocument(real.document, {
+                ...realOptions,
+                expectedNonce: new Uint8Array(32),
+            })
+        ).rejects.toMatchObject({ reason: 'nonce' });
+        await expect(
+            verifyNitroAttestationDocument(real.document, {
+                ...realOptions,
+                policy: { mode: 'nitro', pinnedMeasurements: [measurement] },
+            })
+        ).rejects.toMatchObject({ reason: 'pcr' });
+    });
+
+    it('keeps rejecting indefinite-length encoding outside the signed payload', async () => {
+        const cose = decode(base64ToBuffer(real.document), { useMaps: true }) as unknown[];
+        const indefiniteEnvelope = new Uint8Array([
+            0x9f,
+            ...encode(cose[0]),
+            ...encode(cose[1]),
+            ...encode(cose[2]),
+            ...encode(cose[3]),
+            0xff,
+        ]);
+        await expect(
+            verifyNitroAttestationDocument(bufferToBase64(indefiniteEnvelope.buffer), realOptions)
+        ).rejects.toMatchObject({ reason: 'cbor' });
+    });
+});

package/src/escrow-nitro-attestation.ts

@@ -0,0 +1,317 @@
+import 'reflect-metadata';
+import { decode, encode } from 'cborg';
+import {
+    BasicConstraintsExtension,
+    KeyUsagesExtension,
+    KeyUsageFlags,
+    X509Certificate,
+} from '@peculiar/x509';
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import type { EscrowAttestationPolicy } from './types';
+
+export type NitroAttestationReason =
+    | 'cbor'
+    | 'cose'
+    | 'alg'
+    | 'chain'
+    | 'root'
+    | 'signature'
+    | 'pcr'
+    | 'debug'
+    | 'nonce'
+    | 'freshness'
+    | 'user-data';
+
+/** A fail-closed attestation failure with a stable, non-sensitive reason. */
+export class NitroAttestationError extends Error {
+    constructor(public readonly reason: NitroAttestationReason) {
+        super(`Nitro attestation rejected: ${reason}`);
+        this.name = 'NitroAttestationError';
+    }
+}
+
+const AWS_ROOT_SHA256 = '641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b';
+type NitroPolicy = Extract<EscrowAttestationPolicy, { mode: 'nitro' }>;
+const fail: (reason: NitroAttestationReason) => never = reason => {
+    throw new NitroAttestationError(reason);
+};
+const hex = (bytes: Uint8Array): string =>
+    Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+const bytes = (value: unknown, reason: NitroAttestationReason): Uint8Array =>
+    value instanceof Uint8Array && value.length > 0 ? value : fail(reason);
+const map = (value: unknown, reason: NitroAttestationReason): Map<unknown, unknown> =>
+    value instanceof Map ? value : fail(reason);
+/**
+ * `allowIndefinite` is only for the signed NSM payload: real AWS Nitro documents
+ * encode it as an indefinite-length map (0xbf). That is safe because the COSE
+ * signature below is verified over the original payload bytes, not a re-encoding.
+ * Everything else (COSE envelope, protected header, user_data) stays definite-only.
+ */
+const decodeCbor = (value: Uint8Array, { allowIndefinite = false } = {}): unknown => {
+    try {
+        return decode(value, {
+            useMaps: true,
+            rejectDuplicateMapKeys: true,
+            allowIndefinite,
+            allowUndefined: false,
+            allowNaN: false,
+            allowInfinity: false,
+            allowBigInt: false,
+        });
+    } catch {
+        return fail('cbor');
+    }
+};
+
+/**
+ * P9.1: `user_data` is either the legacy raw SPKI DER (older enclave builds,
+ * accepted during the rollout transition), or a canonical CBOR map
+ * `{0: spki bytes, 1: keyId text, 2: previousKeyIds array<text>}` produced by
+ * `server::attest_user_data` in the enclave. Real P-256 SPKI DER always
+ * starts with the SEQUENCE tag `0x30`, which CBOR decodes as a bare negative
+ * integer (major type 1), never a 3-entry map — so requiring BOTH "decodes as
+ * CBOR" AND "is a map with exactly these three well-typed entries" safely
+ * disambiguates without any separate version marker. A non-throwing probe
+ * (unlike `decodeCbor`/`fail`, whose failure IS the production error path
+ * elsewhere in this file): failing to match either check here means "legacy
+ * format", not "malformed attestation".
+ */
+const decodeUserData = (
+    userData: Uint8Array
+): { spki: Uint8Array; keyId: string; previousKeyIds: string[] } | undefined => {
+    let decoded: unknown;
+    try {
+        decoded = decode(userData, {
+            useMaps: true,
+            rejectDuplicateMapKeys: true,
+            allowIndefinite: false,
+            allowUndefined: false,
+            allowNaN: false,
+            allowInfinity: false,
+            allowBigInt: false,
+        });
+    } catch {
+        return undefined;
+    }
+    if (!(decoded instanceof Map) || decoded.size !== 3) return undefined;
+    const spki = decoded.get(0);
+    const keyId = decoded.get(1);
+    const previousKeyIds = decoded.get(2);
+    const isKeyId = (value: unknown): value is string =>
+        typeof value === 'string' && /^[A-Za-z0-9._-]{1,128}$/.test(value);
+    if (
+        !(spki instanceof Uint8Array) ||
+        spki.length === 0 ||
+        !isKeyId(keyId) ||
+        !Array.isArray(previousKeyIds) ||
+        previousKeyIds.length > 3 ||
+        !previousKeyIds.every(isKeyId)
+    ) {
+        return undefined;
+    }
+    return { spki, keyId, previousKeyIds };
+};
+
+/** Verify signed NSM evidence before trusting its P-256 escrow key (not public_key/KMS key). */
+export const verifyNitroAttestationDocument = async (
+    documentB64: string,
+    {
+        expectedNonce,
+        policy,
+        now = Date.now(),
+    }: {
+        expectedNonce: Uint8Array;
+        policy: NitroPolicy;
+        now?: number;
+    }
+): Promise<{
+    escrowPublicKeySpkiB64: string;
+    /** P9.1: the enclave's own current keyId, bound inside this same signed
+     * document. `undefined` for the legacy user_data format, which never
+     * carried a keyId — callers must not silently trust a plaintext keyId in
+     * that case any more than they did before this field existed. */
+    keyId: string | undefined;
+    /** P9.1: retired keyIds the enclave still accepts for decrypt only, bound
+     * inside this same signed document. Empty for the legacy user_data format. */
+    previousKeyIds: string[];
+    pcrs: Record<number, string>;
+    timestamp: number;
+    moduleId: string;
+    ledgerPublicKey?: string;
+    measurementHash?: string;
+}> => {
+    let document: Uint8Array;
+    try {
+        if (
+            !documentB64 ||
+            documentB64.length > 65536 ||
+            !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(documentB64)
+        )
+            fail('cbor');
+        document = base64ToBuffer(documentB64);
+    } catch {
+        return fail('cbor');
+    }
+    // Only an outer COSE_Sign1 tag is permitted; tags within headers/payload are rejected.
+    const cose = decodeCbor(document[0] === 0xd2 ? document.subarray(1) : document);
+    if (!Array.isArray(cose) || cose.length !== 4) fail('cose');
+    const [protectedValue, unprotectedValue, payloadValue, signatureValue] = cose;
+    const protectedBytes = bytes(protectedValue, 'cose');
+    const protectedHeader = map(decodeCbor(protectedBytes), 'alg');
+    if (protectedHeader.size !== 1 || protectedHeader.get(1) !== -35) fail('alg');
+    if (map(unprotectedValue, 'cose').size !== 0) fail('cose');
+    const payloadBytes = bytes(payloadValue, 'cose');
+    const signature = bytes(signatureValue, 'signature');
+    if (signature.length !== 96) fail('signature');
+    const payload = map(decodeCbor(payloadBytes, { allowIndefinite: true }), 'cbor');
+    const moduleId = payload.get('module_id');
+    const timestamp = payload.get('timestamp');
+    if (typeof moduleId !== 'string' || !moduleId || payload.get('digest') !== 'SHA384')
+        fail('cbor');
+    if (typeof timestamp !== 'number' || !Number.isSafeInteger(timestamp) || timestamp < 0)
+        fail('freshness');
+    const leafDer = bytes(payload.get('certificate'), 'chain');
+    const bundle = payload.get('cabundle');
+    if (!Array.isArray(bundle) || !bundle.length || bundle.length > 16) fail('chain');
+    const ders = bundle.map(value => bytes(value, 'chain'));
+    const rootHash = hex(
+        new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(ders[0])))
+    );
+    if (rootHash !== (policy.rootCertificateSha256 ?? AWS_ROOT_SHA256).toLowerCase()) fail('root');
+    let leaf: X509Certificate;
+    try {
+        const chain = [...ders, leafDer].map(der => new X509Certificate(new Uint8Array(der)));
+        for (let i = 0; i < chain.length; i++) {
+            const cert = chain[i];
+            const issuer = chain[Math.max(0, i - 1)];
+            if (
+                !Number.isFinite(now) ||
+                now < cert.notBefore.getTime() ||
+                now > cert.notAfter.getTime() ||
+                cert.issuer !== issuer.subject ||
+                !(await cert.verify({ publicKey: issuer.publicKey, date: new Date(now) }, crypto))
+            )
+                fail('chain');
+            if (i < chain.length - 1) {
+                const constraints = cert.getExtension(BasicConstraintsExtension);
+                const usage = cert.getExtension(KeyUsagesExtension);
+                if (
+                    !constraints?.ca ||
+                    (constraints.pathLength !== undefined &&
+                        chain.length - i - 2 > constraints.pathLength) ||
+                    (usage && !(usage.usages & KeyUsageFlags.keyCertSign))
+                )
+                    fail('chain');
+            }
+        }
+        leaf = chain[chain.length - 1];
+    } catch {
+        return fail('chain');
+    }
+    try {
+        const key = await crypto.subtle.importKey(
+            'spki',
+            leaf.publicKey.rawData,
+            { name: 'ECDSA', namedCurve: 'P-384' },
+            false,
+            ['verify']
+        );
+        const structure = encode(['Signature1', protectedBytes, new Uint8Array(), payloadBytes]);
+        if (
+            !(await crypto.subtle.verify(
+                { name: 'ECDSA', hash: 'SHA-384' },
+                key,
+                new Uint8Array(signature),
+                new Uint8Array(structure)
+            ))
+        )
+            fail('signature');
+    } catch {
+        return fail('signature');
+    }
+    const rawPcrs = map(payload.get('pcrs'), 'pcr');
+    const pcrs: Record<number, string> = {};
+    for (const [index, value] of rawPcrs) {
+        if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index > 31)
+            fail('pcr');
+        const pcr = bytes(value, 'pcr');
+        if (pcr.length !== 48) fail('pcr');
+        pcrs[index] = hex(pcr);
+    }
+    if (pcrs[0] === '00'.repeat(48)) fail('debug');
+    if (
+        !policy.pinnedMeasurements.some(
+            pin =>
+                typeof pin.pcr0 === 'string' &&
+                typeof pin.pcr1 === 'string' &&
+                typeof pin.pcr2 === 'string' &&
+                pin.pcr0.toLowerCase() === pcrs[0] &&
+                pin.pcr1.toLowerCase() === pcrs[1] &&
+                pin.pcr2.toLowerCase() === pcrs[2]
+        )
+    )
+        fail('pcr');
+    const nonce = bytes(payload.get('nonce'), 'nonce');
+    if (
+        !(expectedNonce instanceof Uint8Array) ||
+        expectedNonce.length !== 32 ||
+        nonce.length !== expectedNonce.length
+    )
+        fail('nonce');
+    let difference = 0;
+    for (let i = 0; i < nonce.length; i++) difference |= nonce[i] ^ expectedNonce[i];
+    if (difference !== 0) fail('nonce');
+    const maxAge = policy.maxAgeMs ?? 300000;
+    if (
+        !Number.isFinite(maxAge) ||
+        maxAge < 0 ||
+        now - timestamp > maxAge ||
+        timestamp > now + 60000
+    )
+        fail('freshness');
+    const userData = bytes(payload.get('user_data'), 'user-data');
+    const newFormat = decodeUserData(new Uint8Array(userData));
+    const spki = newFormat ? newFormat.spki : userData;
+    try {
+        await crypto.subtle.importKey(
+            'spki',
+            new Uint8Array(spki),
+            { name: 'ECDH', namedCurve: 'P-256' },
+            false,
+            []
+        );
+    } catch {
+        return fail('user-data');
+    }
+    const rawLedgerKey = payload.get('public_key');
+    let ledgerPublicKey: string | undefined;
+    let measurementHash: string | undefined;
+    if (rawLedgerKey !== undefined && rawLedgerKey !== null) {
+        const ledger = new Uint8Array(bytes(rawLedgerKey, 'user-data'));
+        if (ledger.length !== 65 || ledger[0] !== 4) fail('user-data');
+        try {
+            await crypto.subtle.importKey(
+                'raw',
+                ledger,
+                { name: 'ECDSA', namedCurve: 'P-256' },
+                false,
+                ['verify']
+            );
+        } catch {
+            return fail('user-data');
+        }
+        const tuple = new Uint8Array(144);
+        for (let i = 0; i < 3; i++) tuple.set(bytes(rawPcrs.get(i), 'pcr'), i * 48);
+        measurementHash = hex(new Uint8Array(await crypto.subtle.digest('SHA-256', tuple)));
+        ledgerPublicKey = bufferToBase64(ledger.buffer);
+    }
+    return {
+        escrowPublicKeySpkiB64: bufferToBase64(new Uint8Array(spki).buffer),
+        keyId: newFormat?.keyId,
+        previousKeyIds: newFormat?.previousKeyIds ?? [],
+        pcrs,
+        timestamp,
+        moduleId,
+        ...(ledgerPublicKey ? { ledgerPublicKey, measurementHash } : {}),
+    };
+};