@auth-craft/aws-cf-stack 1.8.0 → 1.10.0

package/bin/deploy.sh

@@ -17,6 +17,8 @@ export PKG_ROOT
 source "$PKG_ROOT/lib/common.sh"
 # shellcheck source=../lib/deploy-lambda.sh
 source "$PKG_ROOT/lib/deploy-lambda.sh"
+# shellcheck source=../lib/sync-table-gsis.sh
+source "$PKG_ROOT/lib/sync-table-gsis.sh"
 # shellcheck source=../lib/create-admin.sh
 source "$PKG_ROOT/lib/create-admin.sh"
 # shellcheck source=../lib/deploy-gateway.sh
@@ -31,6 +33,8 @@ Usage:
 
 Commands:
   lambda     Deploy DynamoDB + Lambda (CDK). Prints FunctionUrl, ApiBasePath, table.
+             An existing table missing GSIs gets them first, one per update
+             (needs dynamodb:DescribeTable + cloudformation:GetTemplate).
              Use --outputs-file to capture CDK outputs as JSON for your own steps.
   gateway    Deploy the 3 gateway workers (system/tenant/customer) via wrangler,
              wiring BACKEND_URL/base-path/secrets from the live CDK outputs. Reads
@@ -54,6 +58,12 @@ Options (each also reads an env var; the flag wins):
   --edge-gate-secret <v>       env CF_EDGE_GATE_SECRET
   --cf-account-id <v>          env CLOUDFLARE_ACCOUNT_ID
   --cf-api-token <v>           env CLOUDFLARE_API_TOKEN
+  --log-retention-days <n>     CloudWatch log retention (env LAMBDA_LOG_RETENTION_DAYS).
+                               Default: 3 in dev, 30 otherwise. Use 'infinite' to never
+                               expire. Only CloudWatch's fixed set is valid
+                               (1,3,5,7,14,30,60,90,120,150,180,365,400,545,731,…).
+  --tracing <mode>             X-Ray tracing: active|disabled|pass_through
+                               (env LAMBDA_TRACING; default disabled in dev, active otherwise)
   --outputs-file <path>        (lambda) write CDK outputs JSON here for your own steps
   --env-file <path>            Optional: source a file first (flags/env still override)
   --skip-build                 No-op (artifacts are prebuilt in the package)
@@ -89,6 +99,8 @@ while [[ $# -gt 0 ]]; do
     --edge-gate-secret) FLAG[CF_EDGE_GATE_SECRET]="${2:?}"; shift 2 ;;
     --cf-account-id)    FLAG[CLOUDFLARE_ACCOUNT_ID]="${2:?}"; shift 2 ;;
     --cf-api-token)     FLAG[CLOUDFLARE_API_TOKEN]="${2:?}"; shift 2 ;;
+    --log-retention-days) FLAG[LAMBDA_LOG_RETENTION_DAYS]="${2:?}"; shift 2 ;;
+    --tracing)          FLAG[LAMBDA_TRACING]="${2:?}"; shift 2 ;;
     --outputs-file)     OUTPUTS_FILE="${2:?}"; export OUTPUTS_FILE; shift 2 ;;
     --env-file)         ENV_FILE="${2:?}"; shift 2 ;;
     --skip-build)       shift ;;

package/cdk/bin/app.ts

@@ -27,8 +27,7 @@ const env = {
 //   it carries no component so the iss claim stays stable across resources.
 //   Examples: snapshot-commerce-prod-auth-data, snapshot-commerce-prod-auth-api
 
-const appName =
-  process.env.AUTH_CRAFT_APP_NAME || (project === 'default' ? 'auth-craft' : `auth-craft-${project}`);
+const appName = process.env.AUTH_CRAFT_APP_NAME || (project === 'default' ? 'auth-craft' : `auth-craft-${project}`);
 
 // Base name shared by every resource (also AUTH_SYSTEM_NAME / JWT issuer).
 const resourceBase = `${appName}-${stage}-${layer}`;
@@ -50,6 +49,17 @@ const costTags = {
 // Stack / resource naming helper: {app}-{env}-{layer}-{component}
 const nameFor = (component: string) => `${resourceBase}-${component}`;
 
+// GSI rollout: while adding missing GSIs to an existing table one per update, the deploy CLI
+// passes the subset as CDK context (`-c dataGsis=A,B,...`) on that one command line. It is
+// deliberately not an env var: an exported value (shell, --env-file) would leak into the
+// full deploy and make CloudFormation drop every unlisted GSI. Absent or blank = every GSI.
+const dataGsiContext: unknown = app.node.tryGetContext('dataGsis');
+const dataGsiList = (typeof dataGsiContext === 'string' ? dataGsiContext : '')
+  .split(',')
+  .map((name) => name.trim())
+  .filter(Boolean);
+const dataGsis = dataGsiList.length > 0 ? dataGsiList : undefined;
+
 // DynamoDB Stack (data component)
 const dynamodbStack = new DynamoDBStack(app, nameFor('data'), {
   env,
@@ -58,6 +68,7 @@ const dynamodbStack = new DynamoDBStack(app, nameFor('data'), {
   tags: costTags,
   tableName: nameFor('data'),
   stage,
+  ...(dataGsis ? { gsiNames: dataGsis } : {}),
 });
 
 // Lambda Stack (api component)

package/cdk/lib/dynamodb-stack.ts

@@ -1,10 +1,52 @@
 import * as cdk from 'aws-cdk-lib';
 import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
 import type { Construct } from 'constructs';
+import tableSchema from './table-schema.json' with { type: 'json' };
 
 interface DynamoDBStackProps extends cdk.StackProps {
   tableName: string; // {app}-{env}-{layer}-data, e.g. "snapshot-commerce-prod-auth-data"
   stage: string; // "dev" | "staging" | "prod" — passed from the app, single source of truth
+  /**
+   * Only declare these GSIs (schema order kept). Used by the deploy CLI to add missing
+   * GSIs to an existing table one per update — CloudFormation rejects more than one GSI
+   * creation per table update. Omit to declare every GSI in the schema.
+   */
+  gsiNames?: readonly string[];
+}
+
+type KeyAttribute = { name: string; type: string };
+type GsiDefinition = (typeof tableSchema.globalSecondaryIndexes)[number];
+
+// The schema is generated from @auth-craft/database-plugin-dynamodb (TABLE_SCHEMA) by
+// scripts/sync-table-schema.mjs — edit it there, never here.
+export const TABLE_GSI_NAMES: readonly string[] = tableSchema.globalSecondaryIndexes.map((gsi) => gsi.indexName);
+
+function toAttribute(key: KeyAttribute): dynamodb.Attribute {
+  const types: Record<string, dynamodb.AttributeType> = {
+    S: dynamodb.AttributeType.STRING,
+    N: dynamodb.AttributeType.NUMBER,
+    B: dynamodb.AttributeType.BINARY,
+  };
+  const type = types[key.type];
+  if (!type) throw new Error(`Unknown attribute type "${key.type}" for ${key.name}`);
+  return { name: key.name, type };
+}
+
+function toGsiProps(gsi: GsiDefinition): dynamodb.GlobalSecondaryIndexProps {
+  const sortKey = 'sortKey' in gsi && gsi.sortKey ? { sortKey: toAttribute(gsi.sortKey) } : {};
+  const projection = gsi.projection as { type: string; nonKeyAttributes?: string[] };
+  const projectionProps: Pick<dynamodb.GlobalSecondaryIndexProps, 'projectionType' | 'nonKeyAttributes'> =
+    projection.type === 'INCLUDE'
+      ? { projectionType: dynamodb.ProjectionType.INCLUDE, nonKeyAttributes: projection.nonKeyAttributes ?? [] }
+      : projection.type === 'KEYS_ONLY'
+        ? { projectionType: dynamodb.ProjectionType.KEYS_ONLY }
+        : { projectionType: dynamodb.ProjectionType.ALL };
+  return {
+    indexName: gsi.indexName,
+    partitionKey: toAttribute(gsi.partitionKey),
+    ...sortKey,
+    ...projectionProps,
+  };
 }
 
 export class DynamoDBStack extends cdk.Stack {
@@ -13,108 +55,35 @@ export class DynamoDBStack extends cdk.Stack {
   constructor(scope: Construct, id: string, props: DynamoDBStackProps) {
     super(scope, id, props);
 
-    const { tableName, stage } = props;
+    const { tableName, stage, gsiNames } = props;
 
     // Table naming: {app}-{env}-{layer}-data
     // Examples: snapshot-commerce-prod-auth-data, auth-craft-dev-auth-data
 
     this.table = new dynamodb.Table(this, 'AuthCraftTable', {
       tableName,
-      partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING },
+      partitionKey: toAttribute(tableSchema.partitionKey),
+      sortKey: toAttribute(tableSchema.sortKey),
       billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, // On-demand billing
-      timeToLiveAttribute: 'TTL', // Enable TTL for automatic expiration
+      timeToLiveAttribute: tableSchema.ttlAttribute, // Enable TTL for automatic expiration
       pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: stage === 'prod' }, // Enable backups in production
       removalPolicy: stage === 'prod' ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
       deletionProtection: stage === 'prod', // Protect production table from accidental deletion
     });
 
-    // ============================================
-    // SCHEMA_V4 Global Secondary Indexes
-    // ============================================
-
-    // GSI_ActiveSessions: Query active sessions for a user (sparse index)
-    // PK: USR#{userId}, SK: {createdAtMillis}#{sessionId}
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_ActiveSessions',
-      partitionKey: { name: 'activeSessionPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'activeSessionSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.KEYS_ONLY,
-    });
-
-    // GSI_UserSessions: Query all sessions for a user
-    // PK: USR#{userId}, SK: {createdAtMillis}#{sessionId}
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_UserSessions',
-      partitionKey: { name: 'userSessionPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'userSessionSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.KEYS_ONLY,
-    });
-
-    // GSI_UsersByStatus: List users by status (active/inactive)
-    // PK: USR#ACTIVE or USR#INACTIVE, SK: {userId}
-    // INCLUDE: displayName, createdAt
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_UsersByStatus',
-      partitionKey: { name: 'userStatusPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'userStatusSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.INCLUDE,
-      nonKeyAttributes: ['displayName', 'createdAt'],
-    });
-
-    // GSI_UserProviders: Query OAuth providers for a user
-    // PK: USR#{userId}, SK: PRV#{provider}#{externalId}
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_UserProviders',
-      partitionKey: { name: 'userProviderPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'userProviderSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.INCLUDE,
-      nonKeyAttributes: ['userId', 'externalEmail', 'externalName', 'createdAt'],
-    });
-
-    // GSI_UserIdentities: Query all identities for a user (SCHEMA_V4)
-    // PK: USR#{userId}, SK: IDT#{type}#{value}
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_UserIdentities',
-      partitionKey: { name: 'identityUserPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'identityUserSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.INCLUDE,
-      nonKeyAttributes: ['loginEnabled', 'verifiedAt', 'createdAt'],
-    });
-
-    // GSI_UserCredentials: Query all credentials for a user (SCHEMA_V4)
-    // PK: USR#{userId}, SK: CRD#{type}#{credentialId}
-    // INCLUDE: revokedAt, createdAt
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_UserCredentials',
-      partitionKey: { name: 'credentialUserPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'credentialUserSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.INCLUDE,
-      nonKeyAttributes: ['revokedAt', 'createdAt'],
-    });
-
-    // ============================================
-    // SCHEMA_V5+ Global Secondary Indexes
-    // ============================================
-
-    // GSI_UserTenants: Query all tenants for a user (SCHEMA_V7)
-    // PK: USR#{userId}, SK: {createdAtMillis}#{tenantId}
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_UserTenants',
-      partitionKey: { name: 'userTenantPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'userTenantSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.INCLUDE,
-      nonKeyAttributes: ['userStatus', 'role', 'roles', 'perm', 'authPerm', 'isOwner', 'createdAt', 'updatedAt'],
-    });
-
-    // GSI_TenantInvites: Query invites by tenant (SCHEMA_V5)
-    // PK: TNT#{tenantId}, SK: {createdAtMillis}#{inviteId}
-    this.table.addGlobalSecondaryIndex({
-      indexName: 'GSI_TenantInvites',
-      partitionKey: { name: 'inviteTenantPk', type: dynamodb.AttributeType.STRING },
-      sortKey: { name: 'inviteTenantSk', type: dynamodb.AttributeType.STRING },
-      projectionType: dynamodb.ProjectionType.ALL,
-    });
+    // Global Secondary Indexes — see TABLE_SCHEMA in database-plugin-dynamodb for each
+    // index's key layout and access pattern.
+    if (gsiNames && gsiNames.length === 0) {
+      throw new Error('gsiNames is empty — omit it to declare every GSI (an empty list would delete them all)');
+    }
+    const unknown = (gsiNames ?? []).filter((name) => !TABLE_GSI_NAMES.includes(name));
+    if (unknown.length > 0) {
+      throw new Error(`Unknown GSI(s) requested: ${unknown.join(', ')} (schema has ${TABLE_GSI_NAMES.join(', ')})`);
+    }
+    for (const gsi of tableSchema.globalSecondaryIndexes) {
+      if (gsiNames && !gsiNames.includes(gsi.indexName)) continue;
+      this.table.addGlobalSecondaryIndex(toGsiProps(gsi));
+    }
 
     // Outputs
     new cdk.CfnOutput(this, 'TableName', {

package/cdk/lib/lambda-stack.ts

@@ -16,6 +16,78 @@ const __dirname = path.dirname(__filename);
 //   packages/aws-cf-stack/cdk/lib/lambda-stack.ts -> packages/aws-cf-stack/assets/lambda
 const LAMBDA_ASSET_DIR = path.resolve(__dirname, '../../assets/lambda');
 
+// CloudWatch Logs only accepts a fixed set of retention periods — an arbitrary day
+// count is rejected at deploy time. Map the supported values so a typo fails fast at
+// synth (with the valid list) instead of mid-deploy.
+const RETENTION_BY_DAYS: Record<number, logs.RetentionDays> = {
+  1: logs.RetentionDays.ONE_DAY,
+  3: logs.RetentionDays.THREE_DAYS,
+  5: logs.RetentionDays.FIVE_DAYS,
+  7: logs.RetentionDays.ONE_WEEK,
+  14: logs.RetentionDays.TWO_WEEKS,
+  30: logs.RetentionDays.ONE_MONTH,
+  60: logs.RetentionDays.TWO_MONTHS,
+  90: logs.RetentionDays.THREE_MONTHS,
+  120: logs.RetentionDays.FOUR_MONTHS,
+  150: logs.RetentionDays.FIVE_MONTHS,
+  180: logs.RetentionDays.SIX_MONTHS,
+  365: logs.RetentionDays.ONE_YEAR,
+  400: logs.RetentionDays.THIRTEEN_MONTHS,
+  545: logs.RetentionDays.EIGHTEEN_MONTHS,
+  731: logs.RetentionDays.TWO_YEARS,
+  1096: logs.RetentionDays.THREE_YEARS,
+  1827: logs.RetentionDays.FIVE_YEARS,
+  2192: logs.RetentionDays.SIX_YEARS,
+  2557: logs.RetentionDays.SEVEN_YEARS,
+  2922: logs.RetentionDays.EIGHT_YEARS,
+  3288: logs.RetentionDays.NINE_YEARS,
+  3653: logs.RetentionDays.TEN_YEARS,
+};
+
+/**
+ * Resolve the CloudWatch log retention from LAMBDA_LOG_RETENTION_DAYS.
+ * Accepts a supported day count (e.g. "3") or 'infinite' / 'never' to keep logs
+ * forever. Unset → stage default: 3 days in dev (cheap), 1 month otherwise.
+ */
+export function resolveLogRetention(raw: string | undefined, stage: string): logs.RetentionDays {
+  const value = raw?.trim().toLowerCase();
+
+  if (!value) {
+    return stage === 'dev' ? logs.RetentionDays.THREE_DAYS : logs.RetentionDays.ONE_MONTH;
+  }
+
+  if (value === 'infinite' || value === 'never' || value === '0') {
+    return logs.RetentionDays.INFINITE;
+  }
+
+  const days = Number(value);
+  const retention = Number.isInteger(days) ? RETENTION_BY_DAYS[days] : undefined;
+  if (retention === undefined) {
+    throw new Error(
+      `Unsupported LAMBDA_LOG_RETENTION_DAYS: '${raw}'. ` +
+        `CloudWatch Logs accepts only: ${Object.keys(RETENTION_BY_DAYS).join(', ')} (or 'infinite').`,
+    );
+  }
+  return retention;
+}
+
+/**
+ * Resolve X-Ray tracing from LAMBDA_TRACING ('active' | 'disabled').
+ * Unset → disabled in dev (traces are billed per request), active otherwise.
+ */
+export function resolveTracing(raw: string | undefined, stage: string): lambda.Tracing {
+  const value = raw?.trim().toLowerCase();
+
+  if (!value) {
+    return stage === 'dev' ? lambda.Tracing.DISABLED : lambda.Tracing.ACTIVE;
+  }
+  if (value === 'active' || value === 'true' || value === 'enabled') return lambda.Tracing.ACTIVE;
+  if (value === 'disabled' || value === 'false' || value === 'off') return lambda.Tracing.DISABLED;
+  if (value === 'pass_through' || value === 'passthrough') return lambda.Tracing.PASS_THROUGH;
+
+  throw new Error(`Unsupported LAMBDA_TRACING: '${raw}'. Use 'active', 'disabled', or 'pass_through'.`);
+}
+
 interface LambdaStackProps extends cdk.StackProps {
   table: dynamodb.ITable;
   functionName: string; // {app}-{env}-{layer}-api, e.g. "snapshot-commerce-prod-auth-api"
@@ -93,13 +165,24 @@ export class LambdaStack extends cdk.Stack {
     // Naming: functionName = {app}-{env}-{layer}-api (the deployed resource);
     // resourceName = {app}-{env}-{layer} base (AUTH_SYSTEM_NAME / JWT issuer).
 
-    // Log group for Lambda function (matches the function name)
+    // Log group for Lambda function (matches the function name).
+    // Retention drives CloudWatch Logs storage cost, so it is configurable:
+    // LAMBDA_LOG_RETENTION_DAYS accepts any retention CloudWatch supports, plus
+    // 'infinite' (never expire). Unset → a stage-aware default that keeps dev cheap
+    // (3 days) while staging/prod keep a useful history (1 month).
+    const retention = resolveLogRetention(process.env.LAMBDA_LOG_RETENTION_DAYS, stage);
+
     const logGroup = new logs.LogGroup(this, 'AuthLambdaLogGroup', {
       logGroupName: `/aws/lambda/${functionName}`,
-      retention: logs.RetentionDays.ONE_MONTH,
+      retention,
       removalPolicy: stage === 'prod' ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY,
     });
 
+    // X-Ray tracing is billed per trace and is rarely worth it in dev, so it is
+    // opt-out there: LAMBDA_TRACING = 'active' | 'disabled' (default: disabled in
+    // dev, active elsewhere).
+    const tracing = resolveTracing(process.env.LAMBDA_TRACING, stage);
+
     // Lambda function from the PREBUILT bundle shipped in this package.
     // Unlike the in-repo app stack (which uses NodejsFunction to build from
     // src/index.ts at synth time), this self-contained package deploys the
@@ -234,8 +317,8 @@ export class LambdaStack extends cdk.Stack {
         }),
       },
 
-      // Tracing
-      tracing: lambda.Tracing.ACTIVE, // Enable X-Ray tracing
+      // Tracing (X-Ray) — see resolveTracing above; off by default in dev.
+      tracing,
     });
 
     // Grant DynamoDB permissions
@@ -291,6 +374,20 @@ export class LambdaStack extends cdk.Stack {
       exportName: `${this.stackName}-ApiBasePath`,
     });
 
+    // Cost-relevant knobs, echoed so `auth-craft-stack outputs` can show what was
+    // actually deployed (rather than what the caller thinks they set).
+    new cdk.CfnOutput(this, 'LogRetentionDays', {
+      value: String(retention),
+      description: 'CloudWatch log retention in days (0 = never expire)',
+      exportName: `${this.stackName}-LogRetentionDays`,
+    });
+
+    new cdk.CfnOutput(this, 'TracingMode', {
+      value: tracing,
+      description: 'X-Ray tracing mode',
+      exportName: `${this.stackName}-TracingMode`,
+    });
+
     // Output auth system name — used as JWT issuer by Workers to verify tokens
     new cdk.CfnOutput(this, 'AuthSystemName', {
       value: resourceName,

package/cdk/lib/table-schema.json

@@ -0,0 +1,192 @@
+{
+  "partitionKey": {
+    "name": "PK",
+    "type": "S"
+  },
+  "sortKey": {
+    "name": "SK",
+    "type": "S"
+  },
+  "ttlAttribute": "TTL",
+  "globalSecondaryIndexes": [
+    {
+      "indexName": "GSI_ActiveSessions",
+      "partitionKey": {
+        "name": "activeSessionPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "activeSessionSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "KEYS_ONLY"
+      }
+    },
+    {
+      "indexName": "GSI_UserSessions",
+      "partitionKey": {
+        "name": "userSessionPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "userSessionSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "KEYS_ONLY"
+      }
+    },
+    {
+      "indexName": "GSI_UsersByStatus",
+      "partitionKey": {
+        "name": "userStatusPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "userStatusSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "INCLUDE",
+        "nonKeyAttributes": [
+          "displayName",
+          "createdAt"
+        ]
+      }
+    },
+    {
+      "indexName": "GSI_UserProviders",
+      "partitionKey": {
+        "name": "userProviderPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "userProviderSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "INCLUDE",
+        "nonKeyAttributes": [
+          "userId",
+          "externalEmail",
+          "externalName",
+          "createdAt"
+        ]
+      }
+    },
+    {
+      "indexName": "GSI_UserIdentities",
+      "partitionKey": {
+        "name": "identityUserPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "identityUserSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "INCLUDE",
+        "nonKeyAttributes": [
+          "loginEnabled",
+          "verifiedAt",
+          "createdAt"
+        ]
+      }
+    },
+    {
+      "indexName": "GSI_UserCredentials",
+      "partitionKey": {
+        "name": "credentialUserPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "credentialUserSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "INCLUDE",
+        "nonKeyAttributes": [
+          "revokedAt",
+          "createdAt"
+        ]
+      }
+    },
+    {
+      "indexName": "GSI_UserTenants",
+      "partitionKey": {
+        "name": "userTenantPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "userTenantSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "INCLUDE",
+        "nonKeyAttributes": [
+          "userStatus",
+          "role",
+          "roles",
+          "perm",
+          "authPerm",
+          "isOwner",
+          "createdAt",
+          "updatedAt"
+        ]
+      }
+    },
+    {
+      "indexName": "GSI_TenantInvites",
+      "partitionKey": {
+        "name": "inviteTenantPk",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "inviteTenantSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "ALL"
+      }
+    },
+    {
+      "indexName": "GSI_InviteToken",
+      "partitionKey": {
+        "name": "inviteTokenGsi",
+        "type": "S"
+      },
+      "projection": {
+        "type": "KEYS_ONLY"
+      }
+    },
+    {
+      "indexName": "GSI_InviteeEmail",
+      "partitionKey": {
+        "name": "inviteeEmailGsi",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "inviteeEmailTenantSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "ALL"
+      }
+    },
+    {
+      "indexName": "GSI_InviteePhone",
+      "partitionKey": {
+        "name": "inviteePhoneGsi",
+        "type": "S"
+      },
+      "sortKey": {
+        "name": "inviteePhoneTenantSk",
+        "type": "S"
+      },
+      "projection": {
+        "type": "ALL"
+      }
+    }
+  ]
+}

package/lib/common.sh

@@ -259,6 +259,14 @@ print_outputs_json() {
   # in a Service Binding (`[[services]] service = "<worker name>"`) to front auth
   # same-origin via @auth-craft/pages-auth-proxy. The binding lives in the consumer's
   # Pages project, not here — `serviceBindings` is a ready-to-paste snippet.
+  # Cost knobs, read back from the deployed stack so `outputs` reports what is live
+  # rather than what the caller's env happens to say.
+  local logRetention tracingMode
+  logRetention="$(cfn_output "$api_stack" LogRetentionDays)"
+  tracingMode="$(cfn_output "$api_stack" TracingMode)"
+  [[ -n "$logRetention" && "$logRetention" != "None" ]] || logRetention=""
+  [[ -n "$tracingMode" && "$tracingMode" != "None" ]] || tracingMode=""
+
   local mode wnSystem wnTenant wnCustomer bindingService
   mode="$(gateway_mode)"
   if [[ "$mode" == "shared" ]]; then
@@ -288,11 +296,13 @@ print_outputs_json() {
     --arg rpCustomer "${CF_WORKER_ROUTE_PREFIX_CUSTOMER:-/customer}" \
     --arg wnSystem "$wnSystem" --arg wnTenant "$wnTenant" --arg wnCustomer "$wnCustomer" \
     --arg bindingSnippet "$bindingSnippet" \
+    --arg logRetention "$logRetention" --arg tracingMode "$tracingMode" \
     '{stage:$stage, project:$project, region:$region,
       lambdaFunctionUrl:$url, apiBasePath:$base, authSystemName:$name,
       dynamodbTable:$table, backendUrl:$backend,
       jwtPublicKey:$jwtPub, jwtIssuer:$jwtIssuer, jwtAlgorithm:$jwtAlg,
       serviceJwtPublicKey:$svcPub,
+      observability:{logRetentionDays:$logRetention, tracingMode:$tracingMode},
       gatewayUrls:{system:$gwSystem, tenant:$gwTenant, customer:$gwCustomer},
       workerNames:{system:$wnSystem, tenant:$wnTenant, customer:$wnCustomer},
       routePrefixes:{system:$rpSystem, tenant:$rpTenant, customer:$rpCustomer},

package/lib/deploy-lambda.sh

@@ -25,6 +25,10 @@ deploy_lambda() {
   OUTPUTS_FILE="${OUTPUTS_FILE:-$(mktemp -t auth-craft-cdk-outputs.XXXXXX.json)}"
   export OUTPUTS_FILE
 
+  # Existing tables from older package versions may lack GSIs; CloudFormation adds at most
+  # one per update, so add them one at a time before the full deploy below.
+  sync_table_gsis
+
   info "Deploying CDK stacks (${RESOURCE_NAME}-data, ${api_stack})…"
   (
     cd "$CDK_DIR"