@learncard/lca-api-service 1.4.0 → 1.5.1

package/src/helpers/auth.helpers.ts

@@ -5,6 +5,16 @@
 import { environment } from '@environment';
 import { TRPCError } from '@trpc/server';
 import admin from 'firebase-admin';
+import { z } from 'zod';
+import { getKeycloakVerifyOptionsFromEnv, verifyKeycloakJwt } from './keycloak.helpers';
+
+const offlineFirebaseClaimsSchema = z.object({
+    sub: z.string().optional(),
+    uid: z.string().optional(),
+    user_id: z.string().optional(),
+    email: z.string().nullish(),
+    phone_number: z.string().nullish(),
+});
 
 export interface VerifiedUser {
     id: string;
@@ -15,31 +25,35 @@ export interface VerifiedUser {
 
 export type AuthProviderType = 'firebase' | 'supertokens' | 'keycloak' | 'oidc';
 
+const parseOfflineFirebaseClaims = (
+    token: string
+): z.infer<typeof offlineFirebaseClaimsSchema> | undefined => {
+    const payloadPart = token.split('.')[1];
+    if (!payloadPart) return undefined;
+    try {
+        const decoded: unknown = JSON.parse(Buffer.from(payloadPart, 'base64url').toString());
+        return offlineFirebaseClaimsSchema.parse(decoded);
+    } catch {
+        return undefined;
+    }
+};
+
 export async function verifyFirebaseToken(token: string): Promise<VerifiedUser> {
     // E2E test or offline bypass - parse JWT without Firebase Admin verification
     if (environment.IS_E2E_TEST || environment.IS_OFFLINE) {
-        try {
-            const parts = token.split('.');
-            const payloadPart = parts[1];
-            if (parts.length >= 2 && payloadPart) {
-                // Try base64url first, then regular base64
-                let payload;
-                try {
-                    payload = JSON.parse(Buffer.from(payloadPart, 'base64url').toString());
-                } catch {
-                    payload = JSON.parse(Buffer.from(payloadPart, 'base64').toString());
-                }
-                return {
-                    id: payload.sub || payload.uid || payload.user_id || 'offline-user',
-                    email: payload.email,
-                    phone: payload.phone_number,
-                    providerType: 'firebase',
-                };
-            }
-        } catch (e) {
-            console.warn('Failed to parse JWT in offline mode:', e);
-            // Fall through to normal verification
+        const payload = parseOfflineFirebaseClaims(token);
+        if (payload) {
+            return {
+                id: payload.sub || payload.uid || payload.user_id || 'offline-user',
+                email: payload.email ?? undefined,
+                phone: payload.phone_number ?? undefined,
+                providerType: 'firebase',
+            };
         }
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Could not decode Firebase token in offline/E2E mode',
+        });
     }
 
     try {
@@ -52,7 +66,7 @@ export async function verifyFirebaseToken(token: string): Promise<VerifiedUser>
             providerType: 'firebase',
         };
     } catch (error) {
-        console.error('Firebase token verification failed:', error);
+        console.warn('Firebase token verification failed:', error);
         throw new TRPCError({
             code: 'UNAUTHORIZED',
             message: 'Invalid Firebase token',
@@ -70,14 +84,38 @@ export async function verifySuperTokensToken(_token: string): Promise<VerifiedUs
     });
 }
 
-export async function verifyKeycloakToken(_token: string): Promise<VerifiedUser> {
-    // Keycloak verification would go here
-    // This would use the existing verifyKeycloakToken from firebase.helpers.ts
-    // but return a VerifiedUser instead of creating a Firebase user
-    throw new TRPCError({
-        code: 'NOT_IMPLEMENTED',
-        message: 'Keycloak verification not yet implemented for SSS',
-    });
+export async function verifyKeycloakToken(token: string): Promise<VerifiedUser> {
+    const options = getKeycloakVerifyOptionsFromEnv();
+    if (!options) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Keycloak verification is not configured',
+        });
+    }
+    let claims;
+    try {
+        claims = await verifyKeycloakJwt(token, options);
+    } catch {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    if (claims.email !== undefined && claims.email_verified !== true) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Email address is not verified' });
+    }
+    if (claims.phone_number !== undefined && claims.phone_number_verified !== true) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Phone number is not verified' });
+    }
+    if (!claims.email && !claims.phone_number) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Token has no verified contact method',
+        });
+    }
+    return {
+        id: claims.sub,
+        email: claims.email,
+        phone: claims.phone_number,
+        providerType: 'keycloak',
+    };
 }
 
 export async function verifyOidcToken(_token: string): Promise<VerifiedUser> {

package/src/helpers/escrowCancelLink.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildEscrowCancelUrl, resolveEscrowAppBaseUrl } from './escrowCancelLink';
+
+describe('buildEscrowCancelUrl', () => {
+    const holdId = '5b1f6e2e-6e2a-4e8a-9e2a-6e2a4e8a9e2a';
+    const token = 'a'.repeat(64);
+
+    it('builds the expected path and query', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://learncard.app', holdId, token })).toBe(
+            `https://learncard.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+
+    it('never doubles the slash when baseUrl has a trailing slash', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://learncard.app/', holdId, token })).toBe(
+            `https://learncard.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+
+    it('percent-encodes query values that need it', () => {
+        const url = buildEscrowCancelUrl({
+            baseUrl: 'https://learncard.app',
+            holdId: 'weird id/with&chars',
+            token,
+        });
+        expect(url).toBe(
+            `https://learncard.app/recovery/cancel?holdId=weird+id%2Fwith%26chars&token=${token}`
+        );
+        expect(new URL(url).searchParams.get('holdId')).toBe('weird id/with&chars');
+    });
+
+    it('ignores any path segment already present on baseUrl (host + protocol only, matching every tenant appUrl in the registry)', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://vetpass.app', holdId, token })).toBe(
+            `https://vetpass.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+});
+
+describe('resolveEscrowAppBaseUrl', () => {
+    it('falls back to the LearnCard default when the tenant has no appUrl override', () => {
+        expect(
+            resolveEscrowAppBaseUrl({
+                tenant: { id: 'learncard', emailBranding: {}, resolvedVia: 'default' },
+            })
+        ).toBe('https://learncard.app');
+    });
+
+    it('prefers the resolved tenant appUrl', () => {
+        expect(
+            resolveEscrowAppBaseUrl({
+                tenant: {
+                    id: 'vetpass',
+                    emailBranding: { appUrl: 'https://vetpass.app' },
+                    resolvedVia: 'origin',
+                },
+            })
+        ).toBe('https://vetpass.app');
+    });
+});

package/src/helpers/escrowCancelLink.ts

@@ -0,0 +1,38 @@
+/**
+ * Escrow recovery cancel-link deep-link builder.
+ *
+ * Mirrors the existing tenant-branded app-link pattern used elsewhere in the
+ * monorepo (brain-service's `generateClaimUrl` / `generateGuardianApprovalUrl`,
+ * `inbox.helpers.ts`'s `new URL('/notifications', appUrl)`): prefer the
+ * resolved tenant's `TenantBranding.appUrl`, which already falls back to the
+ * LearnCard default (`https://learncard.app`) via `resolveBranding()` when a
+ * tenant has no override.
+ */
+
+import { resolveBranding } from '@learncard/email-templates';
+import type { Context } from '@routes';
+
+/** Base app URL (e.g. `https://vetpass.app`) for constructing escrow deep links. */
+export const resolveEscrowAppBaseUrl = (ctx: Pick<Context, 'tenant'>): string =>
+    resolveBranding(ctx.tenant?.emailBranding).appUrl;
+
+/**
+ * Builds the single-use "cancel this recovery" link sent in the hold-started
+ * email. Uses `URL`/`URLSearchParams` rather than string concatenation so
+ * `holdId`/`token` are correctly percent-encoded and a trailing slash on
+ * `baseUrl` never produces a doubled `//recovery/cancel`.
+ */
+export const buildEscrowCancelUrl = ({
+    baseUrl,
+    holdId,
+    token,
+}: {
+    baseUrl: string;
+    holdId: string;
+    token: string;
+}): string => {
+    const url = new URL('/recovery/cancel', baseUrl);
+    url.searchParams.set('holdId', holdId);
+    url.searchParams.set('token', token);
+    return url.toString();
+};

package/src/helpers/escrowCancelToken.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+    generateEscrowCancelToken,
+    hashEscrowCancelToken,
+    escrowCancelTokenMatches,
+} from './escrowCancelToken';
+
+import type { EscrowHold } from '@models';
+
+const baseHold = (overrides: Partial<EscrowHold> = {}): EscrowHold => {
+    const now = new Date();
+    return {
+        holdRecord: {
+            hold: {
+                holdId: 'hold-id',
+                did: 'did:key:test',
+                shareVersion: 1,
+                blobHash: 'ab'.repeat(32),
+                enrollmentEpoch: 1,
+                releasePolicy: 'hold',
+                clientEphemeralPublicKey: 'public-key',
+                createdLo: 0,
+                createdHi: 0,
+                policyVersion: 1,
+                signature: 'test-signature',
+            },
+            holdDurationMs: 0,
+            ledgerSeq: 0,
+        },
+        _id: 'hold-id',
+        authProvider: { type: 'firebase', id: 'user-1' },
+        primaryDid: 'did:key:test',
+        shareVersion: 1,
+        status: 'pending',
+        identityProofType: 'auth-token',
+        requestedAt: now,
+        releaseAfter: now,
+        releasePolicy: 'hold',
+        clientEphemeralPublicKey: 'public-key',
+        resumeTokenHash: 'a'.repeat(64),
+        notifications: [],
+        createdAt: now,
+        updatedAt: now,
+        ...overrides,
+    };
+};
+
+describe('escrowCancelToken helpers', () => {
+    it('generates unique, high-entropy hex tokens', () => {
+        const token = generateEscrowCancelToken();
+
+        expect(token).toMatch(/^[0-9a-f]{64}$/);
+        expect(generateEscrowCancelToken()).not.toBe(token);
+    });
+
+    it('hashes deterministically without ever equaling the plaintext', () => {
+        const token = generateEscrowCancelToken();
+        const hash = hashEscrowCancelToken(token);
+
+        expect(hash).toMatch(/^[0-9a-f]{64}$/);
+        expect(hash).not.toBe(token);
+        expect(hashEscrowCancelToken(token)).toBe(hash);
+    });
+
+    it('matches the correct token against a pending, unused hold', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({ cancelTokenHash: hashEscrowCancelToken(token) });
+
+        expect(escrowCancelTokenMatches(hold, token)).toBe(true);
+    });
+
+    it('rejects a wrong token', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({ cancelTokenHash: hashEscrowCancelToken(token) });
+
+        expect(escrowCancelTokenMatches(hold, generateEscrowCancelToken())).toBe(false);
+    });
+
+    it('rejects an already-used token', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({
+            cancelTokenHash: hashEscrowCancelToken(token),
+            cancelTokenUsedAt: new Date(),
+        });
+
+        expect(escrowCancelTokenMatches(hold, token)).toBe(false);
+    });
+
+    it('rejects a non-pending hold even with a correct, unused token', () => {
+        const token = generateEscrowCancelToken();
+
+        for (const status of ['cancelled', 'completed', 'expired'] as const) {
+            const hold = baseHold({ status, cancelTokenHash: hashEscrowCancelToken(token) });
+
+            expect(escrowCancelTokenMatches(hold, token)).toBe(false);
+        }
+    });
+
+    it('rejects when no cancel token was ever issued on the hold', () => {
+        const hold = baseHold();
+
+        expect(escrowCancelTokenMatches(hold, generateEscrowCancelToken())).toBe(false);
+    });
+});

package/src/helpers/escrowCancelToken.ts

@@ -0,0 +1,47 @@
+/**
+ * Escrow recovery cancel-link token.
+ *
+ * Mirrors the resume-token primitive in `models/EscrowHold.ts`: a random,
+ * high-entropy token whose SHA-256 hash is stored on the hold so the
+ * plaintext never needs to be persisted. There is no HMAC key involved —
+ * the token's own entropy is the secret, exactly like `resumeTokenHash`.
+ *
+ * The token is single-use (burned via `cancelTokenUsedAt`) and its
+ * effective TTL is the hold's own lifetime: it stops matching the moment
+ * the hold leaves the `pending` status (cancelled, completed, or expired),
+ * so no separate expiry timestamp is needed.
+ *
+ * Never log the plaintext token.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+
+import type { EscrowHold } from '@models';
+
+/** 256 bits of entropy, hex-encoded — same shape as `generateEscrowResumeToken`. */
+export const generateEscrowCancelToken = (): string => randomBytes(32).toString('hex');
+
+/** Plain SHA-256, matching `hashEscrowResumeToken` — the token's own entropy is the secret. */
+export const hashEscrowCancelToken = (token: string): string =>
+    createHash('sha256').update(token).digest('hex');
+
+/**
+ * Timing-safe cancel-token check.
+ *
+ * Returns `false` (never throws) when the hold has no cancel token, the
+ * token was already used, or the hold is no longer `pending` — a cancel
+ * link's effective TTL is the hold's own lifetime, not a separate clock.
+ */
+export const escrowCancelTokenMatches = (hold: EscrowHold, token: string): boolean => {
+    if (hold.status !== 'pending' || hold.cancelTokenUsedAt) return false;
+    const actual = Buffer.from(hashEscrowCancelToken(token), 'hex');
+    const hashes = [
+        ...(hold.cancelTokenHashes ?? []),
+        ...(hold.cancelTokenHash ? [hold.cancelTokenHash] : []),
+    ];
+    // Evaluate every hash, including after a match, rather than short-circuiting.
+    return hashes.reduce((matches, hash) => {
+        const expected = Buffer.from(hash, 'hex');
+        return (actual.length === expected.length && timingSafeEqual(actual, expected)) || matches;
+    }, false);
+};

package/src/helpers/keycloak.helpers.ts

@@ -0,0 +1,120 @@
+import { environment } from '@environment';
+import { TRPCError } from '@trpc/server';
+import { createRemoteJWKSet, decodeJwt, decodeProtectedHeader, jwtVerify } from 'jose';
+import type { JWTVerifyGetKey } from 'jose';
+import { z } from 'zod';
+
+export interface KeycloakVerifyOptions {
+    issuers: string[];
+    audiences: string[];
+}
+
+export interface KeycloakClaims {
+    sub: string;
+    iss: string;
+    typ?: string;
+    azp?: string;
+    aud?: string | string[];
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+const claimsSchema = z.object({
+    sub: z.string().min(1),
+    iss: z.string(),
+    // The payload typ is a Keycloak extension, not a required OIDC claim.
+    typ: z.enum(['ID', 'Bearer']).optional(),
+    azp: z.string().optional(),
+    aud: z.union([z.string(), z.array(z.string())]).optional(),
+    email: z.string().min(1).optional(),
+    email_verified: z.boolean().optional(),
+    phone_number: z.string().min(1).optional(),
+    phone_number_verified: z.boolean().optional(),
+    name: z.string().optional(),
+    picture: z.string().optional(),
+});
+
+const jwksByIssuer = new Map<string, { url: string; resolver: JWTVerifyGetKey }>();
+let resolverForTests: ((issuer: string) => JWTVerifyGetKey) | undefined;
+
+/** Replace JWKS resolution in isolated tests; resetting also clears memoized resolvers. */
+export const setKeycloakJwksResolverForTests = (
+    resolver: ((issuer: string) => JWTVerifyGetKey) | undefined
+): void => {
+    resolverForTests = resolver;
+    jwksByIssuer.clear();
+};
+
+/** Resolve an issuer's JWKS endpoint, optionally using a configured internal hostname. */
+export const getKeycloakIssuerJwksUrl = (issuer: string): string => {
+    for (const entry of (environment.KEYCLOAK_JWKS_URL_OVERRIDES ?? '').split(',')) {
+        const separator = entry.indexOf('=');
+        if (separator < 0) continue;
+        const configuredIssuer = entry.slice(0, separator).trim();
+        const url = entry.slice(separator + 1).trim();
+        if (configuredIssuer === issuer && url) return url;
+    }
+    return `${issuer}/protocol/openid-connect/certs`;
+};
+
+/** Reuse remote key caches and rotation handling per trusted issuer. */
+export const getKeycloakJwks = (issuer: string): JWTVerifyGetKey => {
+    const url = getKeycloakIssuerJwksUrl(issuer);
+    const cached = jwksByIssuer.get(issuer);
+    if (cached?.url === url) return cached.resolver;
+    const resolver = resolverForTests ? resolverForTests(issuer) : createRemoteJWKSet(new URL(url));
+    jwksByIssuer.set(issuer, { url, resolver });
+    return resolver;
+};
+
+/** Verify signature and claims, checking the issuer allowlist before resolving keys. */
+export const verifyKeycloakJwt = async (
+    token: string,
+    opts: KeycloakVerifyOptions
+): Promise<KeycloakClaims> => {
+    decodeProtectedHeader(token);
+    const { iss } = decodeJwt(token);
+    if (typeof iss !== 'string' || !opts.issuers.includes(iss)) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+
+    const { payload } = await jwtVerify(token, getKeycloakJwks(iss), {
+        issuer: iss,
+        algorithms: ['RS256', 'ES256'],
+        clockTolerance: 30,
+    });
+    const result = claimsSchema.safeParse(payload);
+    if (!result.success) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    const claims = result.data;
+    const audiences = typeof claims.aud === 'string' ? [claims.aud] : (claims.aud ?? []);
+    if (claims.azp) audiences.push(claims.azp);
+    if (!audiences.some(audience => opts.audiences.includes(audience))) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    return claims;
+};
+
+/** Read comma-separated issuer and client allowlists from the service configuration. */
+export const getKeycloakVerifyOptionsFromEnv = (): KeycloakVerifyOptions | null => {
+    const split = (value: string | undefined): string[] =>
+        (value ?? '')
+            .split(',')
+            .map(entry => entry.trim())
+            .filter(Boolean);
+    const issuers = split(environment.KEYCLOAK_ISSUERS);
+    if (!issuers.length) return null;
+    const audiences = split(environment.KEYCLOAK_AUDIENCES);
+    if (!audiences.length) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'KEYCLOAK_AUDIENCES is required when KEYCLOAK_ISSUERS is configured',
+        });
+    }
+    return { issuers, audiences };
+};

package/src/helpers/login-ticket.helpers.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import cache from '@cache';
+import { issueLoginTicket } from '@cache/login-tickets';
+import { storeAccessToken, storeAuthorizationCode } from './login-ticket.helpers';
+
+vi.mock('@environment', () => ({ environment: {} }));
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('authentication artifact persistence', () => {
+    const writers = [
+        {
+            name: 'login ticket',
+            write: () =>
+                issueLoginTicket({ subject: 'subject', identityKey: 'email:test@example.com' }),
+        },
+        {
+            name: 'authorization code',
+            write: () =>
+                storeAuthorizationCode({
+                    subject: 'subject',
+                    code: 'code',
+                    scope: 'openid',
+                    clientId: 'broker',
+                    redirectUri: 'https://broker.test/callback',
+                    createdAt: Date.now(),
+                }),
+        },
+        {
+            name: 'access token',
+            write: () =>
+                storeAccessToken('access-token', { subject: 'subject', createdAt: Date.now() }),
+        },
+    ];
+
+    it.each(writers)('rejects a swallowed $name write failure', async ({ name, write }) => {
+        vi.spyOn(cache, 'set').mockResolvedValueOnce(undefined);
+        await expect(write()).rejects.toThrow(`Failed to persist ${name}`);
+    });
+
+    it.each(writers)('propagates a rejected $name write', async ({ write }) => {
+        vi.spyOn(cache, 'set').mockRejectedValueOnce(new Error('Redis unavailable'));
+        await expect(write()).rejects.toThrow('Redis unavailable');
+    });
+});

package/src/helpers/login-ticket.helpers.ts

@@ -0,0 +1,91 @@
+/**
+ * Login tickets, authorization codes, and opaque access tokens for the lca-api
+ * OIDC provider (AD-2).
+ *
+ * Three short-lived, one-time-use artifacts back the "silent hop" login:
+ *  - A **login ticket** is minted after lca-api proves ownership of a contact
+ *    method / federated identity (email code, native Google/Apple). It carries
+ *    the verified claims and the stable subject id.
+ *  - An **authorization code** is minted by `/oidc/authorize` when it redeems a
+ *    login ticket (passed by Keycloak as `login_hint`). Keycloak exchanges the
+ *    code at `/oidc/token` for the signed `id_token`. The code is bound to the
+ *    client + redirect URI it was issued for.
+ *  - An **opaque access token** is minted alongside the id_token so Keycloak's
+ *    broker can call `/oidc/userinfo`. It maps to the same verified claims.
+ *
+ * All live in the cache (Redis in prod, in-memory mock in tests) with short
+ * TTLs. Tickets and codes are consumed (read-then-delete) so neither can be
+ * replayed; the access token is read-only for its short life.
+ */
+
+import crypto from 'node:crypto';
+
+import cache from '@cache';
+import { getDel } from '@cache/getDel';
+
+export const AUTH_CODE_PREFIX = 'oidc-code:';
+export const ACCESS_TOKEN_PREFIX = 'oidc:access:';
+
+export const AUTH_CODE_TTL_SECONDS = 60;
+export const ACCESS_TOKEN_TTL_SECONDS = 300;
+
+export interface SubjectClaims {
+    subject: string;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+export interface AuthorizationCodeData extends SubjectClaims {
+    scope: string;
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    nonce?: string;
+    state?: string;
+    createdAt: number;
+}
+
+export interface AccessTokenData extends SubjectClaims {
+    createdAt: number;
+}
+
+const codeKey = (code: string): string => `${AUTH_CODE_PREFIX}${code}`;
+const accessKey = (accessToken: string): string => `${ACCESS_TOKEN_PREFIX}${accessToken}`;
+
+export const generateAuthorizationCode = (): string => crypto.randomBytes(32).toString('base64url');
+export const generateAccessToken = (): string => crypto.randomBytes(32).toString('base64url');
+
+export const storeAuthorizationCode = async (
+    data: AuthorizationCodeData,
+    ttl = AUTH_CODE_TTL_SECONDS
+): Promise<void> => {
+    const result = await cache.set(codeKey(data.code), JSON.stringify(data), ttl);
+    if (result !== 'OK') throw new Error('Failed to persist authorization code');
+};
+
+export const consumeAuthorizationCode = async (
+    code: string
+): Promise<AuthorizationCodeData | null> => {
+    const raw = await getDel(codeKey(code));
+    if (!raw) return null;
+    return JSON.parse(raw) as AuthorizationCodeData;
+};
+
+export const storeAccessToken = async (
+    accessToken: string,
+    data: AccessTokenData,
+    ttl = ACCESS_TOKEN_TTL_SECONDS
+): Promise<void> => {
+    const result = await cache.set(accessKey(accessToken), JSON.stringify(data), ttl);
+    if (result !== 'OK') throw new Error('Failed to persist access token');
+};
+
+export const getAccessToken = async (accessToken: string): Promise<AccessTokenData | null> => {
+    const raw = await cache.get(accessKey(accessToken));
+    if (!raw) return null;
+    return JSON.parse(raw) as AccessTokenData;
+};