@auth-craft/aws-cf-stack 1.9.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

package/cdk/bin/app.ts

@@ -49,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,
@@ -57,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/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/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"