@ericminassian/platform 0.0.0-stage → 0.1.0

package/src/auth/tokens.ts

@@ -0,0 +1,174 @@
+import { randomBytes } from 'node:crypto';
+import type { AuthBindings, PlatformUser } from '@ericminassian/platform-core';
+import { createRemoteJWKSet, type JWTPayload, errors as joseErrors, jwtVerify } from 'jose';
+import { client } from '../clients.ts';
+
+export interface Tokens {
+  idToken: string;
+  refreshToken?: string;
+}
+
+const jwksCache = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+
+function jwks(uri: string) {
+  let set = jwksCache.get(uri);
+  if (!set) {
+    set = createRemoteJWKSet(new URL(uri), { cooldownDuration: 30_000, cacheMaxAge: 3_600_000 });
+    jwksCache.set(uri, set);
+  }
+  return set;
+}
+
+/** Verify a Cognito ID (or access) token for this app's client and map it to a user. */
+export async function verifyToken(auth: AuthBindings, token: string): Promise<PlatformUser> {
+  const { payload } = await jwtVerify(token, jwks(auth.jwksUri), { issuer: auth.issuer });
+  const use = payload.token_use;
+  if (use === 'id') {
+    const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (!aud.includes(auth.clientId))
+      throw new joseErrors.JWTClaimValidationFailed('unexpected "aud" claim value', payload, 'aud');
+  } else if (use === 'access') {
+    if (payload.client_id !== auth.clientId)
+      throw new joseErrors.JWTClaimValidationFailed(
+        'unexpected "client_id" claim value',
+        payload,
+        'client_id',
+      );
+  } else {
+    throw new joseErrors.JWTClaimValidationFailed('unexpected "token_use" claim value', payload, 'token_use');
+  }
+  return toUser(payload);
+}
+
+export function isExpiredError(e: unknown): boolean {
+  return e instanceof joseErrors.JWTExpired;
+}
+
+export function toUser(p: JWTPayload): PlatformUser {
+  const str = (k: string) => (typeof p[k] === 'string' ? (p[k] as string) : undefined);
+  const name =
+    str('name') ?? ([str('given_name'), str('family_name')].filter(Boolean).join(' ') || undefined);
+  const groups = Array.isArray(p['cognito:groups']) ? (p['cognito:groups'] as unknown[]).map(String) : [];
+  const user: PlatformUser = { id: String(p.sub), groups };
+  const email = str('email');
+  if (email) user.email = email;
+  if (p.email_verified !== undefined)
+    user.emailVerified = p.email_verified === true || p.email_verified === 'true';
+  if (name) user.name = name;
+  return user;
+}
+
+// ---------------------------------------------------------------- hosted login (cognito mode)
+
+async function tokenRequest(auth: AuthBindings, params: Record<string, string>): Promise<Tokens> {
+  const res = await fetch(`${auth.loginUrl.replace(/\/$/, '')}/oauth2/token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ client_id: auth.clientId, ...params }),
+  });
+  if (!res.ok)
+    throw new Error(`Cognito token endpoint returned ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  const json = (await res.json()) as { id_token?: string; refresh_token?: string };
+  if (!json.id_token) throw new Error('Cognito token endpoint returned no id_token');
+  return { idToken: json.id_token, ...(json.refresh_token ? { refreshToken: json.refresh_token } : {}) };
+}
+
+export function exchangeCode(
+  auth: AuthBindings,
+  code: string,
+  verifier: string,
+  redirectUri: string,
+): Promise<Tokens> {
+  return tokenRequest(auth, {
+    grant_type: 'authorization_code',
+    code,
+    code_verifier: verifier,
+    redirect_uri: redirectUri,
+  });
+}
+
+export async function refreshTokens(auth: AuthBindings, refreshToken: string): Promise<Tokens> {
+  if (auth.mode === 'local') {
+    const { InitiateAuthCommand } = await import('@aws-sdk/client-cognito-identity-provider');
+    const out = await (await client('cognito')).send(
+      new InitiateAuthCommand({
+        ClientId: auth.clientId,
+        AuthFlow: 'REFRESH_TOKEN_AUTH',
+        AuthParameters: { REFRESH_TOKEN: refreshToken },
+      }),
+    );
+    const id = out.AuthenticationResult?.IdToken;
+    if (!id) throw new Error('refresh returned no id token');
+    return { idToken: id };
+  }
+  return tokenRequest(auth, { grant_type: 'refresh_token', refresh_token: refreshToken });
+}
+
+// ---------------------------------------------------------------- local sign-in (plat dev)
+
+function errorName(e: unknown): string {
+  return (e as { name?: string })?.name ?? '';
+}
+
+/**
+ * `plat dev` sign-in against the AWS Emulator's Cognito (no hosted UI there):
+ * create the user if needed, set a throwaway password, and authenticate.
+ */
+export async function localSignIn(auth: AuthBindings, email: string, name?: string): Promise<Tokens> {
+  const cognito = await client('cognito');
+  const {
+    AdminCreateUserCommand,
+    AdminInitiateAuthCommand,
+    AdminSetUserPasswordCommand,
+    InitiateAuthCommand,
+  } = await import('@aws-sdk/client-cognito-identity-provider');
+  try {
+    await cognito.send(
+      new AdminCreateUserCommand({
+        UserPoolId: auth.userPoolId,
+        Username: email,
+        MessageAction: 'SUPPRESS',
+        UserAttributes: [
+          { Name: 'email', Value: email },
+          { Name: 'email_verified', Value: 'true' },
+          ...(name ? [{ Name: 'name', Value: name }] : []),
+        ],
+      }),
+    );
+  } catch (e) {
+    if (errorName(e) !== 'UsernameExistsException') throw e;
+  }
+  const password = `Pp1!${randomBytes(18).toString('base64url')}`;
+  await cognito.send(
+    new AdminSetUserPasswordCommand({
+      UserPoolId: auth.userPoolId,
+      Username: email,
+      Password: password,
+      Permanent: true,
+    }),
+  );
+  const params = { USERNAME: email, PASSWORD: password };
+  let result: { IdToken?: string; RefreshToken?: string } | undefined;
+  try {
+    const out = await cognito.send(
+      new AdminInitiateAuthCommand({
+        UserPoolId: auth.userPoolId,
+        ClientId: auth.clientId,
+        AuthFlow: 'ADMIN_USER_PASSWORD_AUTH',
+        AuthParameters: params,
+      }),
+    );
+    result = out.AuthenticationResult;
+  } catch {
+    const out = await cognito.send(
+      new InitiateAuthCommand({
+        ClientId: auth.clientId,
+        AuthFlow: 'USER_PASSWORD_AUTH',
+        AuthParameters: params,
+      }),
+    );
+    result = out.AuthenticationResult;
+  }
+  if (!result?.IdToken) throw new Error('Local sign-in returned no tokens');
+  return { idToken: result.IdToken, ...(result.RefreshToken ? { refreshToken: result.RefreshToken } : {}) };
+}

package/src/bindings.ts

@@ -0,0 +1,35 @@
+import { BINDINGS_ENV, type Bindings, decodeBindings } from '@ericminassian/platform-core';
+
+let cached: Bindings | undefined;
+
+/**
+ * The stage's bindings, decoded lazily from `PLATFORM_BINDINGS` on first use
+ * so importing the SDK never throws; using a resource without bindings does.
+ */
+export function getBindings(): Bindings {
+  if (!cached) cached = decodeBindings(process.env[BINDINGS_ENV]);
+  return cached;
+}
+
+/** Bindings if present, otherwise undefined (telemetry, health). */
+export function tryBindings(): Bindings | undefined {
+  try {
+    return getBindings();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Override bindings (tests). Pass undefined to re-read the environment. */
+export function setBindings(b: Bindings | undefined): void {
+  cached = b;
+}
+
+export function region(): string {
+  return tryBindings()?.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? 'us-east-1';
+}
+
+/** True under `plat dev` / `plat test` (AWS Emulator). */
+export function isEmulator(): boolean {
+  return Boolean(process.env.AWS_ENDPOINT_URL);
+}

package/src/clients.ts

@@ -0,0 +1,98 @@
+import type { CognitoIdentityProviderClient } from '@aws-sdk/client-cognito-identity-provider';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import type { EventBridgeClient } from '@aws-sdk/client-eventbridge';
+import type { LambdaClient } from '@aws-sdk/client-lambda';
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { SQSClient } from '@aws-sdk/client-sqs';
+import type { SSMClient } from '@aws-sdk/client-ssm';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { isEmulator, region } from './bindings.ts';
+
+/**
+ * AWS clients, created on first use. Under `plat dev` / `plat test` the
+ * standard `AWS_ENDPOINT_URL` points every client at the AWS Emulator and
+ * `NODE_EXTRA_CA_CERTS` trusts its certificate; nothing else differs.
+ *
+ * Only DynamoDB is imported eagerly (most apps use it, and `db.raw()` is
+ * synchronous). Everything else is a dynamic import, which esbuild keeps in
+ * the same bundle but evaluates lazily — so cold starts only pay for the
+ * services a request actually touches.
+ */
+export interface Clients {
+  ddb: DynamoDBDocumentClient;
+  sqs: SQSClient;
+  events: EventBridgeClient;
+  s3: S3Client;
+  ssm: SSMClient;
+  lambda: LambdaClient;
+  cognito: CognitoIdentityProviderClient;
+}
+
+export type LazyClientName = Exclude<keyof Clients, 'ddb'>;
+
+/** Minimal client shape (tests may substitute `{ send }` fakes). */
+export interface SendClient {
+  send(command: unknown): Promise<unknown>;
+}
+
+const instances: Partial<Record<keyof Clients, unknown>> = {};
+const pending: Partial<Record<keyof Clients, Promise<unknown>>> = {};
+const overrides: Partial<Record<keyof Clients, SendClient>> = {};
+
+function config(): { region: string; endpoint?: string } {
+  const endpoint = process.env.AWS_ENDPOINT_URL;
+  return { region: region(), ...(endpoint ? { endpoint } : {}) };
+}
+
+const lazyFactories: { [K in LazyClientName]: () => Promise<Clients[K]> } = {
+  sqs: async () => new (await import('@aws-sdk/client-sqs')).SQSClient(config()),
+  events: async () => new (await import('@aws-sdk/client-eventbridge')).EventBridgeClient(config()),
+  s3: async () =>
+    new (await import('@aws-sdk/client-s3')).S3Client({
+      ...config(),
+      ...(isEmulator() ? { forcePathStyle: true } : {}),
+    }),
+  ssm: async () => new (await import('@aws-sdk/client-ssm')).SSMClient(config()),
+  lambda: async () => new (await import('@aws-sdk/client-lambda')).LambdaClient(config()),
+  cognito: async () =>
+    new (await import('@aws-sdk/client-cognito-identity-provider')).CognitoIdentityProviderClient(config()),
+};
+
+/** The DynamoDB document client (synchronous). */
+export function ddbClient(): DynamoDBDocumentClient {
+  const o = overrides.ddb;
+  if (o) return o as unknown as DynamoDBDocumentClient;
+  let c = instances.ddb as DynamoDBDocumentClient | undefined;
+  if (!c) {
+    c = DynamoDBDocumentClient.from(new DynamoDBClient(config()), {
+      marshallOptions: { removeUndefinedValues: true, convertClassInstanceToMap: true },
+    });
+    instances.ddb = c;
+  }
+  return c;
+}
+
+export async function client<K extends LazyClientName>(name: K): Promise<Clients[K]> {
+  const o = overrides[name];
+  if (o) return o as unknown as Clients[K];
+  const existing = instances[name];
+  if (existing) return existing as Clients[K];
+  pending[name] ??= lazyFactories[name]().then((c) => {
+    instances[name] = c;
+    return c;
+  });
+  return pending[name] as Promise<Clients[K]>;
+}
+
+/** Substitute a client (tests). `undefined` removes the override. */
+export function setClient(name: keyof Clients, fake: SendClient | undefined): void {
+  if (fake) overrides[name] = fake;
+  else delete overrides[name];
+}
+
+/** Drop cached clients (tests that change region/endpoint between runs). */
+export function resetClients(): void {
+  for (const k of Object.keys(instances) as (keyof Clients)[]) delete instances[k];
+  for (const k of Object.keys(pending) as (keyof Clients)[]) delete pending[k];
+  for (const k of Object.keys(overrides) as (keyof Clients)[]) delete overrides[k];
+}

package/src/context.ts

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { newSpanId, newTraceId, type PlatformUser } from '@ericminassian/platform-core';
+
+/** Per-request / per-job context carried through async calls. */
+export interface RequestContext {
+  trace: string;
+  /** Span id of the root (request or job). */
+  span: string;
+  /** performance.now() when the root started, for span offsets. */
+  startedAt: number;
+  /** Set-Cookie values produced while handling the request (e.g. token refresh). */
+  cookies: string[];
+  /** Matched route pattern, set by the router integration. */
+  route?: string;
+  /** Resolved user (undefined = not looked up yet, null = signed out). */
+  user?: PlatformUser | null;
+  /** Job name for error attribution in workers. */
+  job?: string;
+  /** Error a framework handled itself (e.g. a Hono app's onError), for telemetry. */
+  error?: unknown;
+}
+
+const storage = new AsyncLocalStorage<RequestContext>();
+
+export function currentContext(): RequestContext | undefined {
+  return storage.getStore();
+}
+
+export function runWithContext<T>(ctx: RequestContext, fn: () => T): T {
+  return storage.run(ctx, fn);
+}
+
+export function newContext(trace?: string | null): RequestContext {
+  return { trace: trace || newTraceId(), span: newSpanId(), startedAt: performance.now(), cookies: [] };
+}
+
+/** Trace id of the current request/job, or a fresh one outside any context. */
+export function currentTrace(): string {
+  return storage.getStore()?.trace ?? newTraceId();
+}
+
+/** Parse a W3C `traceparent` header (`00-<32 hex trace>-<16 hex span>-<flags>`). */
+export function parseTraceparent(header: string | null | undefined): string | undefined {
+  if (!header) return undefined;
+  const m = /^[\da-f]{2}-([\da-f]{32})-[\da-f]{16}-[\da-f]{2}$/i.exec(header.trim());
+  return m?.[1]?.toLowerCase();
+}
+
+/**
+ * Record the route pattern (e.g. `/api/todos/:id`) for the current request's
+ * telemetry. Hono apps get this automatically; other frameworks can call it.
+ */
+export function setRoute(pattern: string): void {
+  const ctx = storage.getStore();
+  if (ctx) ctx.route = pattern;
+}