@attestplane/attestplane 0.0.1 → 0.0.4-alpha

package/dist/signing/providers.js

@@ -0,0 +1,230 @@
+// SPDX-FileCopyrightText: 2026 The Attestplane Authors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Concrete `KeyProvider` implementations — TypeScript mirror of
+ * `sdk/python/src/attestplane/signing/providers.py` (architect plan § 1 D
+ * + T6 review decision 4).
+ *
+ * Four providers:
+ *
+ * - `InMemoryKeyProvider` — tests / dev; optional 32-byte seed for
+ *   deterministic keys.
+ * - `FileKeyProvider` — PKCS#8 PEM file on disk.
+ * - `EnvKeyProvider` — PKCS#8 PEM bytes from `process.env`.
+ * - `MultiSignerProvider` — plurality (any-of-n) composite per architect
+ *   plan § 1 H. NOT a `KeyProvider` subclass: returns an array.
+ *
+ * Ed25519 recipe (load-bearing R1 risk mitigation):
+ *
+ * - **Seed → KeyObject**: PKCS#8 DER wrap path (RFC 8410). Node 22's
+ *   JWK importer requires the public `x` alongside `d`, which would
+ *   force us to recompute the point first — the PKCS#8 path wraps the
+ *   raw 32-byte seed with a constant 16-byte prefix, byte-equal to the
+ *   blob `cryptography`'s `Ed25519PrivateKey.from_private_bytes(seed)`
+ *   produces when serialised. This deviates from the architect's
+ *   initial JWK recipe per the T6 implementation revision dated
+ *   2026-05-17 (see `docs/architecture/adr_0005_t6_review_20260517.md`).
+ * - **SPKI DER export**: via the intermediate
+ *   `createPublicKey(privateKey).export({format:'der', type:'spki'})` so
+ *   the public-key bytes are byte-equal to Python's
+ *   `Ed25519PrivateKey.public_key().public_bytes(DER, SubjectPublicKeyInfo)`.
+ */
+import { createPrivateKey, createPublicKey, generateKeyPairSync, } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { KeyProvider, KeyProviderError, SIGNATURE_SCHEMA_VERSION, deriveKeyId, } from './base.js';
+const ED25519_SEED_LEN = 32;
+/**
+ * RFC 8410 Ed25519 PKCS#8 wrapper — constant 16-byte prefix concatenated
+ * with the 32-byte seed produces a valid 48-byte PKCS#8 DER blob. Used
+ * because Node 22's JWK importer requires the public `x` field alongside
+ * `d`, which would force us to recompute the public point first — the
+ * PKCS#8 path sidesteps that entirely and is byte-equal to the recipe
+ * used by Python `cryptography`'s `Ed25519PrivateKey.from_private_bytes()`.
+ *
+ * Decode: `SEQUENCE { INTEGER 0, AlgorithmIdentifier {OID 1.3.101.112},
+ * OCTET STRING { OCTET STRING <32 byte seed> } }`.
+ */
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+export function seedToPrivateKey(seed) {
+    if (seed.length !== ED25519_SEED_LEN) {
+        throw new KeyProviderError(`Ed25519 seed must be exactly ${ED25519_SEED_LEN} bytes, got ${seed.length}`);
+    }
+    const pkcs8 = Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(seed)]);
+    return createPrivateKey({ key: pkcs8, format: 'der', type: 'pkcs8' });
+}
+export function exportPublicKeyDer(privateKey) {
+    const pub = createPublicKey(privateKey);
+    return new Uint8Array(pub.export({ format: 'der', type: 'spki' }));
+}
+function loadPemPrivateKey(pemBytes, passphrase, context) {
+    let key;
+    try {
+        key = createPrivateKey(passphrase !== undefined
+            ? { key: pemBytes, format: 'pem', passphrase }
+            : { key: pemBytes, format: 'pem' });
+    }
+    catch (exc) {
+        throw new KeyProviderError(`${context}: failed to load PEM key: ${exc.message}`);
+    }
+    if (key.asymmetricKeyType !== 'ed25519') {
+        throw new KeyProviderError(`${context}: key is not Ed25519 (got asymmetricKeyType=${String(key.asymmetricKeyType)})`);
+    }
+    return key;
+}
+function materialFromPrivateKey(privateKey) {
+    const publicKeyDer = exportPublicKeyDer(privateKey);
+    return {
+        privateKey,
+        publicKeyDer,
+        signingCertChain: [],
+        keyId: deriveKeyId(publicKeyDer),
+    };
+}
+/**
+ * Holds an Ed25519 keypair in process memory.
+ *
+ * Suitable for tests, ephemeral substrates, and deployments where the
+ * key is generated at startup and never persisted.
+ *
+ * When `seed` is supplied, the same seed always produces the same
+ * Ed25519 key — required for conformance vectors. When `seed` is
+ * absent, a fresh random key is generated via Node `crypto`
+ * `generateKeyPairSync('ed25519')`.
+ */
+export class InMemoryKeyProvider extends KeyProvider {
+    provider_id;
+    schema_version = SIGNATURE_SCHEMA_VERSION;
+    _privateKey;
+    constructor(options = {}) {
+        super();
+        const providerId = options.provider_id ?? 'in-memory';
+        if (!providerId) {
+            throw new Error('InMemoryKeyProvider provider_id must be non-empty');
+        }
+        this.provider_id = providerId;
+        if (options.seed !== undefined) {
+            this._privateKey = seedToPrivateKey(options.seed);
+        }
+        else {
+            const { privateKey } = generateKeyPairSync('ed25519');
+            this._privateKey = privateKey;
+        }
+    }
+    getSigningMaterial() {
+        return materialFromPrivateKey(this._privateKey);
+    }
+}
+/**
+ * Loads an Ed25519 private key from a PKCS#8 PEM file on disk.
+ *
+ * The file is read on EVERY `getSigningMaterial()` call; intentional
+ * design so file rotation (deployer replaces the file out-of-band) is
+ * picked up on the next signing call.
+ */
+export class FileKeyProvider extends KeyProvider {
+    provider_id;
+    schema_version = SIGNATURE_SCHEMA_VERSION;
+    _path;
+    _passphrase;
+    constructor(path, options = {}) {
+        super();
+        if (!path) {
+            throw new Error('FileKeyProvider path must be non-empty');
+        }
+        this._path = path;
+        this._passphrase =
+            options.passphrase !== undefined ? Buffer.from(options.passphrase) : undefined;
+        this.provider_id = options.provider_id ?? `file:${path}`;
+    }
+    getSigningMaterial() {
+        let pemBytes;
+        try {
+            pemBytes = readFileSync(this._path);
+        }
+        catch (exc) {
+            const err = exc;
+            if (err.code === 'ENOENT') {
+                throw new KeyProviderError(`FileKeyProvider: key file not found at ${this._path}`);
+            }
+            throw new KeyProviderError(`FileKeyProvider: cannot read ${this._path}: ${err.message}`);
+        }
+        const key = loadPemPrivateKey(pemBytes, this._passphrase, `FileKeyProvider(${this._path})`);
+        return materialFromPrivateKey(key);
+    }
+}
+/**
+ * Loads an Ed25519 private key from `process.env[envVar]`.
+ *
+ * The env var must contain a PEM-encoded PKCS#8 key (typical when a
+ * secret manager injects the key at runtime).
+ */
+export class EnvKeyProvider extends KeyProvider {
+    provider_id;
+    schema_version = SIGNATURE_SCHEMA_VERSION;
+    _envVar;
+    _passphrase;
+    constructor(envVar, options = {}) {
+        super();
+        if (!envVar) {
+            throw new Error('EnvKeyProvider envVar must be non-empty');
+        }
+        this._envVar = envVar;
+        this._passphrase =
+            options.passphrase !== undefined ? Buffer.from(options.passphrase) : undefined;
+        this.provider_id = options.provider_id ?? `env:${envVar}`;
+    }
+    getSigningMaterial() {
+        const pemText = process.env[this._envVar];
+        if (pemText === undefined) {
+            throw new KeyProviderError(`EnvKeyProvider: env var ${JSON.stringify(this._envVar)} is not set`);
+        }
+        if (pemText.trim().length === 0) {
+            throw new KeyProviderError(`EnvKeyProvider: env var ${JSON.stringify(this._envVar)} is empty`);
+        }
+        const key = loadPemPrivateKey(pemText, this._passphrase, `EnvKeyProvider(${this._envVar})`);
+        return materialFromPrivateKey(key);
+    }
+}
+// ----- MultiSignerProvider -----
+/**
+ * Plurality (any-of-n) composite per architect plan § 1 H.
+ *
+ * Holds N `KeyProvider` instances and exposes their signing materials
+ * as a list. The `Signer` iterates and produces one `SignatureRecord`
+ * per provider per signed event.
+ *
+ * Intentionally NOT a `KeyProvider` subclass: a `KeyProvider` returns
+ * one `SigningMaterial`; this composite returns a list.
+ *
+ * Verification semantics: any valid signature from any trust-rooted
+ * `key_id` counts as "segment signed". Plurality, NOT k-of-n threshold
+ * (architect plan § 1 H — threshold explicitly out of scope).
+ */
+export class MultiSignerProvider {
+    _providers;
+    constructor(providers) {
+        if (providers.length === 0) {
+            throw new Error('MultiSignerProvider requires at least one provider');
+        }
+        const seen = new Set();
+        for (const p of providers) {
+            if (seen.has(p.provider_id)) {
+                throw new Error('MultiSignerProvider providers must have distinct provider_id values');
+            }
+            seen.add(p.provider_id);
+            if (p.schema_version !== SIGNATURE_SCHEMA_VERSION) {
+                throw new Error(`provider ${JSON.stringify(p.provider_id)} has schema_version=` +
+                    `${p.schema_version}; this composite handles only ` +
+                    `SIGNATURE_SCHEMA_VERSION=${SIGNATURE_SCHEMA_VERSION}`);
+            }
+        }
+        this._providers = [...providers];
+    }
+    get provider_ids() {
+        return this._providers.map((p) => p.provider_id);
+    }
+    getSigningMaterials() {
+        return this._providers.map((p) => p.getSigningMaterial());
+    }
+}
+//# sourceMappingURL=providers.js.map

package/dist/signing/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/signing/providers.ts"],"names":[],"mappings":"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"}

package/dist/signing/signer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Signer — TypeScript mirror of
+ * `sdk/python/src/attestplane/signing/signer.py` per T6 review § 1
+ * decision 5: sync-only API. Background-worker mode is explicitly
+ * deferred (TS `anchoring.ts` already lacks the worker pattern; no
+ * need to break parity here).
+ *
+ * Two payload builders are exposed (matching Python):
+ *
+ * - `buildSegmentHeadPayload(chain_id, head)` — canonical-JSON over a
+ *   fixed 5-key object `{chain_id, event_hash, schema_version, seq,
+ *   signature_schema_version}`. Cross-language byte-stable.
+ * - `buildPerEventPayload(event)` — canonical AuditEvent bytes
+ *   bytes. Byte-identical to what `hashEvent()` hashes; already locked
+ *   by v0.0.1-alpha `vectors.json`.
+ */
+import type { AuditEvent, ChainHead, ChainedEvent } from '../types.js';
+import { type KeyProvider, type SignatureRecord } from './base.js';
+import { MultiSignerProvider } from './providers.js';
+/**
+ * Construct the canonical-JSON bytes signed in segment-head mode.
+ *
+ * Locked recipe per architect review § 3:
+ *
+ * ```
+ * { "chain_id": "<str>",
+ *   "event_hash": "<lowercase hex>",
+ *   "schema_version": 1,
+ *   "seq": <int>,
+ *   "signature_schema_version": 1 }
+ * ```
+ *
+ * Cross-language byte-stability gate (T6 conformance assertion #1).
+ */
+export declare function buildSegmentHeadPayload(chainId: string, head: ChainHead): Uint8Array;
+/**
+ * Per-event mode signs the canonical bytes of the AuditEvent. Identical
+ * to `hashEvent`'s canonicalization call → already cross-language byte
+ * stable via `vectors.json`.
+ */
+export declare function buildPerEventPayload(event: AuditEvent): Uint8Array;
+export interface SignerOptions {
+    readonly chain_id: string;
+    readonly key_provider: KeyProvider | MultiSignerProvider;
+    readonly now?: () => Date;
+}
+/**
+ * Event-signing producer (sync-only TS variant).
+ *
+ * Methods:
+ * - `signEvent(event)` — per-event mode; signs canonical AuditEvent bytes.
+ * - `signSegmentHead(head)` — segment-head mode; signs the locked
+ *   5-key payload.
+ *
+ * Each method returns `SignatureRecord[]` (one entry per signing
+ * material, supporting `MultiSignerProvider` plurality).
+ */
+export declare class Signer {
+    private readonly _chainId;
+    private readonly _keyProvider;
+    private readonly _now;
+    constructor(options: SignerOptions);
+    signEvent(event: ChainedEvent): SignatureRecord[];
+    signSegmentHead(head: ChainHead): SignatureRecord[];
+}
+//# sourceMappingURL=signer.d.ts.map

package/dist/signing/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EACL,KAAK,WAAW,EAGhB,KAAK,eAAe,EAGrB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAUrD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,CAWpF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAElE;AAqCD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,WAAW,GAAG,mBAAmB,CAAC;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,OAAO,EAAE,aAAa;IASlC,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,EAAE;IAkBjD,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,EAAE;CAuBpD"}

package/dist/signing/signer.js

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: 2026 The Attestplane Authors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Signer — TypeScript mirror of
+ * `sdk/python/src/attestplane/signing/signer.py` per T6 review § 1
+ * decision 5: sync-only API. Background-worker mode is explicitly
+ * deferred (TS `anchoring.ts` already lacks the worker pattern; no
+ * need to break parity here).
+ *
+ * Two payload builders are exposed (matching Python):
+ *
+ * - `buildSegmentHeadPayload(chain_id, head)` — canonical-JSON over a
+ *   fixed 5-key object `{chain_id, event_hash, schema_version, seq,
+ *   signature_schema_version}`. Cross-language byte-stable.
+ * - `buildPerEventPayload(event)` — canonical AuditEvent bytes
+ *   bytes. Byte-identical to what `hashEvent()` hashes; already locked
+ *   by v0.0.1-alpha `vectors.json`.
+ */
+import { sign as ed25519Sign } from 'node:crypto';
+import { canonicalize } from '../canonical.js';
+import { SCHEMA_VERSION as CHAIN_SCHEMA_VERSION, canonicalizeAuditEvent } from '../hashchain.js';
+import { SIGNATURE_SCHEMA_VERSION, SigningError, } from './base.js';
+import { MultiSignerProvider } from './providers.js';
+function bytesToHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        out += bytes[i].toString(16).padStart(2, '0');
+    }
+    return out;
+}
+/**
+ * Construct the canonical-JSON bytes signed in segment-head mode.
+ *
+ * Locked recipe per architect review § 3:
+ *
+ * ```
+ * { "chain_id": "<str>",
+ *   "event_hash": "<lowercase hex>",
+ *   "schema_version": 1,
+ *   "seq": <int>,
+ *   "signature_schema_version": 1 }
+ * ```
+ *
+ * Cross-language byte-stability gate (T6 conformance assertion #1).
+ */
+export function buildSegmentHeadPayload(chainId, head) {
+    if (!chainId) {
+        throw new SigningError('segment-head signing requires non-empty chain_id');
+    }
+    return canonicalize({
+        chain_id: chainId,
+        event_hash: bytesToHex(head.event_hash),
+        schema_version: CHAIN_SCHEMA_VERSION,
+        seq: head.seq,
+        signature_schema_version: SIGNATURE_SCHEMA_VERSION,
+    });
+}
+/**
+ * Per-event mode signs the canonical bytes of the AuditEvent. Identical
+ * to `hashEvent`'s canonicalization call → already cross-language byte
+ * stable via `vectors.json`.
+ */
+export function buildPerEventPayload(event) {
+    return canonicalizeAuditEvent(event);
+}
+function resolveMaterials(provider) {
+    if (provider instanceof MultiSignerProvider) {
+        return provider.getSigningMaterials();
+    }
+    return [provider.getSigningMaterial()];
+}
+function makeSignatureRecord(mat, args) {
+    // Ed25519 in node:crypto: algorithm=null per Node docs.
+    const signature = new Uint8Array(ed25519Sign(null, Buffer.from(args.signed_payload), mat.privateKey));
+    return {
+        signature_schema_version: SIGNATURE_SCHEMA_VERSION,
+        signed_seq: args.signed_seq,
+        signed_event_hash: args.signed_event_hash,
+        signature,
+        key_id: mat.keyId,
+        public_key_der: mat.publicKeyDer,
+        signing_cert_chain: mat.signingCertChain,
+        signed_at: args.signed_at,
+        signature_mode: args.signature_mode,
+        signed_payload: args.signed_payload,
+    };
+}
+/**
+ * Event-signing producer (sync-only TS variant).
+ *
+ * Methods:
+ * - `signEvent(event)` — per-event mode; signs canonical AuditEvent bytes.
+ * - `signSegmentHead(head)` — segment-head mode; signs the locked
+ *   5-key payload.
+ *
+ * Each method returns `SignatureRecord[]` (one entry per signing
+ * material, supporting `MultiSignerProvider` plurality).
+ */
+export class Signer {
+    _chainId;
+    _keyProvider;
+    _now;
+    constructor(options) {
+        if (!options.chain_id) {
+            throw new Error('Signer chain_id must be non-empty');
+        }
+        this._chainId = options.chain_id;
+        this._keyProvider = options.key_provider;
+        this._now = options.now ?? (() => new Date());
+    }
+    signEvent(event) {
+        const materials = resolveMaterials(this._keyProvider);
+        const signedAt = this._now();
+        if (Number.isNaN(signedAt.getTime())) {
+            throw new SigningError('Signer.signEvent requires a valid Date for now()');
+        }
+        const payload = buildPerEventPayload(event.event);
+        return materials.map((mat) => makeSignatureRecord(mat, {
+            signed_seq: event.seq,
+            signed_event_hash: event.event_hash,
+            signed_payload: payload,
+            signature_mode: 'per_event',
+            signed_at: signedAt,
+        }));
+    }
+    signSegmentHead(head) {
+        if (head.seq < 0) {
+            throw new SigningError('Signer.signSegmentHead requires a real chain head (seq >= 0); ' +
+                'refusing to sign genesis sentinel');
+        }
+        const materials = resolveMaterials(this._keyProvider);
+        const signedAt = this._now();
+        if (Number.isNaN(signedAt.getTime())) {
+            throw new SigningError('Signer.signSegmentHead requires a valid Date for now()');
+        }
+        const payload = buildSegmentHeadPayload(this._chainId, head);
+        return materials.map((mat) => makeSignatureRecord(mat, {
+            signed_seq: head.seq,
+            signed_event_hash: head.event_hash,
+            signed_payload: payload,
+            signature_mode: 'segment_head',
+            signed_at: signedAt,
+        }));
+    }
+}
+//# sourceMappingURL=signer.js.map

package/dist/signing/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/signing/signer.ts"],"names":[],"mappings":"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"}

package/dist/signing/trust_roots.d.ts

@@ -0,0 +1,71 @@
+/**
+ * TrustRoots loader — TypeScript mirror of
+ * `sdk/python/src/attestplane/signing/trust_roots.py`.
+ *
+ * Per T6 review § 1 decision 3: **JSON only** in TS. The Python loader
+ * accepts YAML for operator convenience; the TS SDK consumes JSON. Same
+ * schema fields exactly. Operators convert YAML→JSON via `yq` if
+ * needed. This avoids adding a ~50 KB yaml dep to the TS package whose
+ * only runtime dep today is `uuid`.
+ *
+ * Schema:
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "keys": [
+ *     {
+ *       "key_id": "<32 lowercase hex chars>",
+ *       "public_key_der_b64": "<base64 SPKI>",
+ *       "valid_from": "2026-05-17T00:00:00Z",
+ *       "valid_until": "2027-05-17T00:00:00Z",
+ *       "provider_id": "<optional>",
+ *       "label": "<optional>"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Strict invariants (mirror Python):
+ * - `version` must equal 1.
+ * - `keys` must be a non-empty array.
+ * - Each entry's `key_id` must equal `deriveKeyId(b64decode(public_key_der_b64))`.
+ * - `valid_from < valid_until`, both UTC-aware ISO-8601.
+ * - Top-level + per-entry `additionalProperties` rejected.
+ * - File size > 1 MB rejected (DoS mitigation).
+ */
+import { SigningError } from './base.js';
+export declare class TrustRootsError extends SigningError {
+    constructor(message: string);
+}
+export interface TrustRootEntry {
+    readonly key_id: string;
+    readonly public_key_der: Uint8Array;
+    readonly valid_from: Date;
+    readonly valid_until: Date;
+    readonly provider_id: string | null;
+    readonly label: string | null;
+}
+export declare class TrustRoots {
+    readonly version: number;
+    readonly entries: readonly TrustRootEntry[];
+    constructor(version: number, entries: readonly TrustRootEntry[]);
+    lookup(keyId: string): TrustRootEntry | null;
+}
+/**
+ * Load + validate a TrustRoots JSON file.
+ *
+ * - File size cap 1 MB.
+ * - Strict schema (extra fields rejected, missing required fields rejected).
+ * - Every entry's `key_id` cross-checked against `deriveKeyId()`.
+ * - Duplicate `key_id` rejected.
+ */
+export declare function loadTrustRoots(path: string): TrustRoots;
+/**
+ * Validate an already-parsed JSON value as a `TrustRoots`. Used by
+ * `loadTrustRoots` and exposed so callers who fetched the JSON from
+ * a non-file source (HTTP, secret manager) can validate without an
+ * intermediate disk write.
+ */
+export declare function parseTrustRoots(raw: unknown, source?: string): TrustRoots;
+//# sourceMappingURL=trust_roots.d.ts.map

package/dist/signing/trust_roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust_roots.d.ts","sourceRoot":"","sources":["../../src/signing/trust_roots.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AAQtD,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;gBAEhC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,cAAc,EAAE;IAK/D,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;CAM7C;AA0ID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CA8BvD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,SAAa,GAAG,UAAU,CAsD7E"}