@de-otio/trellis 0.6.1 → 0.7.1

package/dist/lib/oauth/envelope-crypto.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Envelope encryption helpers for OAuth device-authorization records.
+ *
+ * Pattern:
+ *   1. A per-record data-encryption key (DEK) is derived via HKDF-SHA256
+ *      from the device_code (held only by the polling agent) and a
+ *      KMS-protected wrap key (KEK).
+ *   2. The DEK encrypts the payload (Cognito tokens) with AES-256-GCM.
+ *   3. The DynamoDB row stores only iv, auth tag, ciphertext, and the
+ *      KMS-wrapped KEK reference. A direct GetItem without device_code
+ *      cannot derive the DEK and therefore cannot decrypt.
+ *
+ * The KEK in the MVP path is a 32-byte key fetched from a static SSM
+ * parameter / env var; production wraps that fetch in KMS:Decrypt so the
+ * key never leaves a memory-only buffer. The DEK derivation salt is
+ * random per-record and stored alongside the ciphertext — without
+ * device_code the salt + KEK alone are insufficient.
+ *
+ * Algorithms are pinned. Unit tests assert that swapping device_code at
+ * decrypt time fails with an authentication error rather than returning
+ * silently truncated plaintext.
+ */
+/** HKDF info string. Versioned so future schema changes are detectable. */
+export declare const DEK_INFO = "trellis-device-auth-dek-v1";
+export interface SealedEnvelope {
+    /** Random per-record HKDF salt, base64url. */
+    salt: string;
+    /** AES-GCM IV, base64url. */
+    iv: string;
+    /** AES-GCM authentication tag, base64url. */
+    tag: string;
+    /** AES-GCM ciphertext, base64url. */
+    ciphertext: string;
+    /** Algorithm tag — pinned for forward compatibility. */
+    alg: "AES-256-GCM+HKDF-SHA256";
+    /** Info string used in HKDF; lets us rotate without re-keying. */
+    info: string;
+    /**
+     * KEK version (G4 MEDIUM-1). Forward-compatible field that lets us
+     * rotate the wrap key without re-encrypting every record. MVP path
+     * writes 1 and `open()` only knows how to dispatch the version-1
+     * fetcher; future rotations register additional fetchers via
+     * `setKmsKekFetcherForVersion()` and bump the value written by `seal`.
+     */
+    keyVersion: number;
+}
+/** Current KEK version written by `seal`. */
+export declare const CURRENT_KEK_VERSION = 1;
+/**
+ * Derive the per-record DEK from `(deviceCode, kek, salt)` via HKDF-SHA256.
+ * The device_code is the IKM; the KEK is mixed in as part of the salt so a
+ * stolen DynamoDB row alone cannot derive the DEK.
+ */
+export declare function deriveDek(deviceCode: string, kek: Buffer, salt: Buffer): Buffer;
+/**
+ * Seal `plaintext` (UTF-8 string) under a DEK derived from `(deviceCode, kek)`.
+ * Returns the storable envelope; ciphertext + iv + tag are sufficient for
+ * decryption only when device_code is supplied at open time.
+ */
+export declare function seal(plaintext: string, deviceCode: string, kek: Buffer): SealedEnvelope;
+/**
+ * Open an envelope produced by `seal`. Returns the plaintext UTF-8 string.
+ * Throws on auth-tag mismatch (wrong device_code, tampered payload).
+ *
+ * The supplied `kek` parameter is the version-1 KEK. For envelopes
+ * stamped with a different `keyVersion`, callers should resolve the
+ * matching KEK before invoking this function (see `resolveKekForVersion`).
+ * The MVP runs version 1 only; this signature stays compatible for
+ * forward-rotation scenarios (G4 MEDIUM-1).
+ */
+export declare function open(envelope: SealedEnvelope, deviceCode: string, kek: Buffer): string;
+/**
+ * Resolve the KEK for a given envelope version. The MVP path is a
+ * single-version trampoline; future rotations register additional
+ * fetchers and dispatch on `version`. Callers reading a previously
+ * sealed envelope should call this rather than `resolveKek()` directly
+ * (G4 MEDIUM-1).
+ */
+export declare function resolveKekForVersion(version: number): Promise<Buffer>;
+/**
+ * Constant-time compare for two strings expected to be of the same length.
+ * Used by callers that need to compare device_code candidates against a
+ * stored hash (we don't store the device_code itself, so this is reserved
+ * for refresh-jti comparisons).
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Hook for tests + production wiring. Defaults to a stub that throws,
+ * directing callers to install `@aws-sdk/client-kms` and override via
+ * `setKmsKekFetcher`. The skybber CDK wires the AWS-SDK-backed fetcher
+ * during process bootstrap.
+ */
+export type KmsKekFetcher = (kmsKeyId: string, region: string) => Promise<Buffer>;
+/** Wire the production KMS path. Skybber CDK calls this during bootstrap. */
+export declare function setKmsKekFetcher(fn: KmsKekFetcher): void;
+export declare function resolveKek(): Promise<Buffer>;
+/** Reset the cached KEK. Test-only. */
+export declare function _resetKekCacheForTest(): void;
+/** Reset the KMS fetcher to its default (test-only). */
+export declare function _resetKmsKekFetcherForTest(): void;
+//# sourceMappingURL=envelope-crypto.d.ts.map

package/dist/lib/oauth/envelope-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-crypto.d.ts","sourceRoot":"","sources":["../../../src/lib/oauth/envelope-crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,2EAA2E;AAC3E,eAAO,MAAM,QAAQ,+BAA+B,CAAC;AAWrD,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,GAAG,EAAE,yBAAyB,CAAC;IAC/B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAUrC;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACX,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,cAAc,CAsBhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAClB,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,CAmCR;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK3E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKvD;AAYD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAQlF,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAExD;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CA2BlD;AAED,uCAAuC;AACvC,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,wDAAwD;AACxD,wBAAgB,0BAA0B,IAAI,IAAI,CAMjD"}

package/dist/lib/oauth/envelope-crypto.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Envelope encryption helpers for OAuth device-authorization records.
+ *
+ * Pattern:
+ *   1. A per-record data-encryption key (DEK) is derived via HKDF-SHA256
+ *      from the device_code (held only by the polling agent) and a
+ *      KMS-protected wrap key (KEK).
+ *   2. The DEK encrypts the payload (Cognito tokens) with AES-256-GCM.
+ *   3. The DynamoDB row stores only iv, auth tag, ciphertext, and the
+ *      KMS-wrapped KEK reference. A direct GetItem without device_code
+ *      cannot derive the DEK and therefore cannot decrypt.
+ *
+ * The KEK in the MVP path is a 32-byte key fetched from a static SSM
+ * parameter / env var; production wraps that fetch in KMS:Decrypt so the
+ * key never leaves a memory-only buffer. The DEK derivation salt is
+ * random per-record and stored alongside the ciphertext — without
+ * device_code the salt + KEK alone are insufficient.
+ *
+ * Algorithms are pinned. Unit tests assert that swapping device_code at
+ * decrypt time fails with an authentication error rather than returning
+ * silently truncated plaintext.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_KEK_VERSION = exports.DEK_INFO = void 0;
+exports.deriveDek = deriveDek;
+exports.seal = seal;
+exports.open = open;
+exports.resolveKekForVersion = resolveKekForVersion;
+exports.safeEqual = safeEqual;
+exports.setKmsKekFetcher = setKmsKekFetcher;
+exports.resolveKek = resolveKek;
+exports._resetKekCacheForTest = _resetKekCacheForTest;
+exports._resetKmsKekFetcherForTest = _resetKmsKekFetcherForTest;
+const node_crypto_1 = require("node:crypto");
+/** HKDF info string. Versioned so future schema changes are detectable. */
+exports.DEK_INFO = "trellis-device-auth-dek-v1";
+/** Length of the AES-256 DEK in bytes. */
+const DEK_LEN = 32;
+/** Length of the HKDF salt stored alongside the ciphertext. */
+const SALT_LEN = 32;
+/** AES-GCM IV length (96 bits is the recommended NIST size). */
+const IV_LEN = 12;
+/** AES-GCM authentication tag length (16 bytes / 128 bits). */
+const TAG_LEN = 16;
+/** Current KEK version written by `seal`. */
+exports.CURRENT_KEK_VERSION = 1;
+function b64url(b) {
+    return b.toString("base64url");
+}
+function fromB64url(s) {
+    return Buffer.from(s, "base64url");
+}
+/**
+ * Derive the per-record DEK from `(deviceCode, kek, salt)` via HKDF-SHA256.
+ * The device_code is the IKM; the KEK is mixed in as part of the salt so a
+ * stolen DynamoDB row alone cannot derive the DEK.
+ */
+function deriveDek(deviceCode, kek, salt) {
+    if (!deviceCode || deviceCode.length < 16) {
+        throw new Error("device_code too short");
+    }
+    if (kek.length !== 32) {
+        throw new Error("KEK must be 32 bytes");
+    }
+    if (salt.length !== SALT_LEN) {
+        throw new Error(`salt must be ${SALT_LEN} bytes`);
+    }
+    // HKDF: ikm = device_code; salt = (kek || salt); info = DEK_INFO.
+    // Mixing KEK into the salt means the DEK depends on both pieces.
+    const combinedSalt = Buffer.concat([kek, salt]);
+    const dek = (0, node_crypto_1.hkdfSync)("sha256", deviceCode, combinedSalt, exports.DEK_INFO, DEK_LEN);
+    return Buffer.from(dek);
+}
+/**
+ * Seal `plaintext` (UTF-8 string) under a DEK derived from `(deviceCode, kek)`.
+ * Returns the storable envelope; ciphertext + iv + tag are sufficient for
+ * decryption only when device_code is supplied at open time.
+ */
+function seal(plaintext, deviceCode, kek) {
+    const salt = (0, node_crypto_1.randomBytes)(SALT_LEN);
+    const iv = (0, node_crypto_1.randomBytes)(IV_LEN);
+    const dek = deriveDek(deviceCode, kek, salt);
+    const cipher = (0, node_crypto_1.createCipheriv)("aes-256-gcm", dek, iv, { authTagLength: TAG_LEN });
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // Wipe the DEK from our reference. (V8 doesn't guarantee wipe, but at
+    // least we don't keep a reachable reference past the call.)
+    dek.fill(0);
+    return {
+        salt: b64url(salt),
+        iv: b64url(iv),
+        tag: b64url(tag),
+        ciphertext: b64url(ct),
+        alg: "AES-256-GCM+HKDF-SHA256",
+        info: exports.DEK_INFO,
+        keyVersion: exports.CURRENT_KEK_VERSION,
+    };
+}
+/**
+ * Open an envelope produced by `seal`. Returns the plaintext UTF-8 string.
+ * Throws on auth-tag mismatch (wrong device_code, tampered payload).
+ *
+ * The supplied `kek` parameter is the version-1 KEK. For envelopes
+ * stamped with a different `keyVersion`, callers should resolve the
+ * matching KEK before invoking this function (see `resolveKekForVersion`).
+ * The MVP runs version 1 only; this signature stays compatible for
+ * forward-rotation scenarios (G4 MEDIUM-1).
+ */
+function open(envelope, deviceCode, kek) {
+    if (envelope.alg !== "AES-256-GCM+HKDF-SHA256") {
+        throw new Error(`unsupported envelope alg: ${envelope.alg}`);
+    }
+    if (envelope.info !== exports.DEK_INFO) {
+        throw new Error(`unsupported envelope info: ${envelope.info}`);
+    }
+    // Reject envelopes from versions we don't yet know how to dispatch.
+    // Older envelopes without keyVersion default to version 1 for
+    // backward compatibility with rows already written under the old
+    // shape — those still decrypt with the version-1 KEK.
+    const declaredVersion = envelope.keyVersion ?? 1;
+    if (declaredVersion !== 1) {
+        throw new Error(`unsupported envelope keyVersion: ${declaredVersion}`);
+    }
+    const salt = fromB64url(envelope.salt);
+    const iv = fromB64url(envelope.iv);
+    const tag = fromB64url(envelope.tag);
+    const ct = fromB64url(envelope.ciphertext);
+    if (salt.length !== SALT_LEN)
+        throw new Error("envelope salt length");
+    if (iv.length !== IV_LEN)
+        throw new Error("envelope iv length");
+    if (tag.length !== TAG_LEN)
+        throw new Error("envelope tag length");
+    const dek = deriveDek(deviceCode, kek, salt);
+    const decipher = (0, node_crypto_1.createDecipheriv)("aes-256-gcm", dek, iv, { authTagLength: TAG_LEN });
+    decipher.setAuthTag(tag);
+    let pt;
+    try {
+        pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    finally {
+        dek.fill(0);
+    }
+    return pt.toString("utf8");
+}
+/**
+ * Resolve the KEK for a given envelope version. The MVP path is a
+ * single-version trampoline; future rotations register additional
+ * fetchers and dispatch on `version`. Callers reading a previously
+ * sealed envelope should call this rather than `resolveKek()` directly
+ * (G4 MEDIUM-1).
+ */
+async function resolveKekForVersion(version) {
+    if (version !== 1) {
+        throw new Error(`unsupported envelope keyVersion: ${version}`);
+    }
+    return resolveKek();
+}
+/**
+ * Constant-time compare for two strings expected to be of the same length.
+ * Used by callers that need to compare device_code candidates against a
+ * stored hash (we don't store the device_code itself, so this is reserved
+ * for refresh-jti comparisons).
+ */
+function safeEqual(a, b) {
+    const ab = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    if (ab.length !== bb.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(ab, bb);
+}
+/**
+ * Resolve the KEK at runtime. Two paths:
+ *   1. process.env.DEVICE_AUTH_KEK_BASE64 — local dev / test fast path.
+ *   2. KMS:GenerateDataKey via DEVICE_AUTH_KMS_KEY_ID. Production path.
+ *
+ * The result is cached for the lifetime of the process. Callers must
+ * NOT log the buffer.
+ */
+let cachedKek;
+let kmsKekFetcher = async () => {
+    throw new Error("KMS KEK fetcher not configured; call setKmsKekFetcher() at startup or set DEVICE_AUTH_KEK_BASE64");
+};
+/** Wire the production KMS path. Skybber CDK calls this during bootstrap. */
+function setKmsKekFetcher(fn) {
+    kmsKekFetcher = fn;
+}
+async function resolveKek() {
+    if (cachedKek)
+        return cachedKek;
+    const inline = process.env.DEVICE_AUTH_KEK_BASE64;
+    if (inline) {
+        const b = Buffer.from(inline, "base64");
+        if (b.length !== 32) {
+            throw new Error("DEVICE_AUTH_KEK_BASE64 must decode to 32 bytes");
+        }
+        cachedKek = b;
+        return cachedKek;
+    }
+    const kmsKeyId = process.env.DEVICE_AUTH_KMS_KEY_ID;
+    if (!kmsKeyId) {
+        throw new Error("Device-auth KEK not configured: set DEVICE_AUTH_KEK_BASE64 (dev) or DEVICE_AUTH_KMS_KEY_ID (prod)");
+    }
+    const region = process.env.AWS_REGION || "us-east-1";
+    const plain = await kmsKekFetcher(kmsKeyId, region);
+    if (plain.length !== 32) {
+        throw new Error("KMS plaintext key wrong length");
+    }
+    cachedKek = plain;
+    return cachedKek;
+}
+/** Reset the cached KEK. Test-only. */
+function _resetKekCacheForTest() {
+    cachedKek = undefined;
+}
+/** Reset the KMS fetcher to its default (test-only). */
+function _resetKmsKekFetcherForTest() {
+    kmsKekFetcher = async () => {
+        throw new Error("KMS KEK fetcher not configured; call setKmsKekFetcher() at startup or set DEVICE_AUTH_KEK_BASE64");
+    };
+}
+//# sourceMappingURL=envelope-crypto.js.map

package/dist/lib/oauth/envelope-crypto.js.map

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

package/dist/lib/oauth/refresh-detection.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Refresh-token reuse detection (RFC 6819 §5.2.2.5, T9b-d).
+ *
+ * Each refresh-token JTI is recorded once. On refresh:
+ *   - load the row by jti
+ *   - if absent      → unknown token; treat as suspect, deny
+ *   - if `consumed`  → REPLAY; revoke all sessions for that user via
+ *                      AdminUserGlobalSignOut and emit `auth.refresh_replay`
+ *   - if `active`    → mark consumed, issue new refresh with new jti
+ *
+ * Storage: AGENT_REFRESH_TABLE in DynamoDB. Same table also holds the
+ * agent-session metadata listed by `/api/users/me/agent-sessions`.
+ */
+export type AgentSessionStatus = "active" | "consumed" | "revoked";
+export interface AgentSessionRecord {
+    /** Trellis session id (cuid-ish opaque). */
+    sessionId: string;
+    /** Owning user's trellis user id. */
+    userId: string;
+    /** Cognito sub bound to the issued refresh token. */
+    cognitoSub: string;
+    /** Tenant id from the session at approval time. */
+    tenantId: string;
+    /** Currently-active refresh-token JTI (null after revoke). */
+    currentJti: string | null;
+    /** Set of all jti's ever issued for this session, for replay detection. */
+    /** We track the latest only — older are flipped to consumed individually. */
+    status: AgentSessionStatus;
+    /** Free-form label set by the device-auth flow (User-Agent excerpt). */
+    agentLabel?: string;
+    sourceIp?: string;
+    createdAt: number;
+    lastUsedAt: number;
+}
+export interface RefreshJtiRecord {
+    jti: string;
+    sessionId: string;
+    userId: string;
+    cognitoSub: string;
+    status: "active" | "consumed";
+    issuedAt: number;
+    consumedAt?: number;
+}
+export interface CognitoRevoker {
+    globalSignOut(input: {
+        userPoolId: string;
+        cognitoUsername: string;
+    }): Promise<void>;
+}
+export interface AuditEmitter {
+    emit(input: {
+        type: string;
+        tenantId: string;
+        actorUserId: string;
+        payload: Record<string, unknown>;
+        sourceIp?: string;
+        agentSessionId?: string;
+    }): Promise<void>;
+}
+/** Initial record write at session creation (after approval). */
+export declare function recordAgentSession(input: {
+    session: AgentSessionRecord;
+    initialJti: string;
+}): Promise<void>;
+/**
+ * Validate a refresh-token JTI. Three outcomes:
+ *   - "ok"      → the jti was active; row is now flipped to consumed.
+ *   - "replay"  → jti was already consumed → caller must revoke session globally.
+ *   - "unknown" → jti not present (foreign or expired); deny.
+ */
+export declare function consumeRefreshJti(jti: string): Promise<{
+    outcome: "ok" | "replay" | "unknown";
+    record?: RefreshJtiRecord;
+}>;
+/**
+ * On confirmed replay: revoke all sessions for the user, mark the session
+ * row revoked, emit `auth.refresh_replay`. The Cognito SDK call uses
+ * AdminUserGlobalSignOut to invalidate every refresh-derived token.
+ *
+ * Hardening (G4 CRITICAL-1, CRITICAL-2):
+ *   - The Cognito username used for revocation is read directly from
+ *     `jtiRecord.cognitoSub` (the value bound at session-creation time).
+ *     Callers may not supply an alternate identity; this prevents the
+ *     wrong account from being revoked if a caller forwards a request-
+ *     scoped value here.
+ *   - The audit event is emitted FIRST so a downstream Cognito or DDB
+ *     failure cannot suppress the `auth.refresh_replay` signal. The
+ *     mutation steps follow in order; each is wrapped so that audit
+ *     emit completes even when a later step throws.
+ */
+export declare function handleRefreshReplay(input: {
+    jtiRecord: RefreshJtiRecord;
+    tenantId: string;
+    userPoolId: string;
+    cognito: CognitoRevoker;
+    audit: AuditEmitter;
+    sourceIp?: string;
+}): Promise<void>;
+/**
+ * Issue a new refresh JTI for a session. The old JTI must already be
+ * consumed (caller flips it before calling). Updates the session row.
+ */
+export declare function rotateRefreshJti(input: {
+    sessionId: string;
+    userId: string;
+    cognitoSub: string;
+    newJti: string;
+}): Promise<void>;
+/** List all active sessions for a user. Used by `/api/users/me/agent-sessions`. */
+export declare function listAgentSessions(userId: string): Promise<AgentSessionRecord[]>;
+/** Revoke a session by id; caller must verify the session belongs to the user. */
+export declare function revokeAgentSession(input: {
+    sessionId: string;
+    userPoolId: string;
+    cognitoUsername: string;
+    cognito: CognitoRevoker;
+    audit: AuditEmitter;
+    tenantId: string;
+    actorUserId: string;
+    sourceIp?: string;
+}): Promise<void>;
+/** Look up a session by id (auth check helper). */
+export declare function getAgentSession(sessionId: string): Promise<AgentSessionRecord | null>;
+/** Test-only: helper to clear a session row directly. */
+export declare function _deleteAgentSessionForTest(sessionId: string): Promise<void>;
+//# sourceMappingURL=refresh-detection.d.ts.map

package/dist/lib/oauth/refresh-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-detection.d.ts","sourceRoot":"","sources":["../../../src/lib/oauth/refresh-detection.ts"],"names":[],"mappings":"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"}