@raindancers/raindancers-crew 0.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,253 @@
+# @raindancers/raindancers-crew
+
+A CDK construct that provisions a **self-hosted [KiroCrew](https://github.com/kirodotdev/KiroCrew) gateway** on a single EC2 instance in your own AWS account, reached over **SSM Session Manager** — no inbound ports, no SSH key.
+
+It is a pipeline-native, version-controlled port of the upstream `kirocrew-ec2` CloudFormation template. Where the native `kirocrew cloud launch` is an imperative one-shot, this construct lets you deploy the same shape **through your own CDK pipeline**, under **your** naming, permissions boundary, and OIDC deploy role — so a remote crew becomes a reviewed, repeatable, diffable artifact like everything else you ship.
+
+## Getting started
+
+### 1. Install
+
+```bash
+npm install @raindancers/raindancers-crew
+```
+
+The package targets `aws-cdk-lib` ^2.260.0 and `constructs` ^10 (peer dependencies — your app supplies them).
+
+### 2. Define a stack
+
+A complete stack that stands up an EC2 crew with off-box backup. Everything is
+typed and compiles as-is — fill in your account, region, VPC lookup, and
+permissions-boundary ARN.
+
+```ts
+import { App, Stack, StackProps } from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { Construct } from 'constructs';
+import {
+  RemoteCrewInstance,
+  CrewArchitecture,
+  CrewBackupBucket,
+} from '@raindancers/raindancers-crew';
+
+class CrewStack extends Stack {
+  constructor(scope: Construct, id: string, props: StackProps) {
+    super(scope, id, props);
+
+    // Your existing VPC (or ec2.Vpc.fromLookup(...)).
+    const vpc = ec2.Vpc.fromLookup(this, 'Vpc', { isDefault: true });
+
+    // Durable, versioned, KMS-encrypted backup destination.
+    const backup = new CrewBackupBucket(this, 'CrewBackup');
+
+    new RemoteCrewInstance(this, 'Crew', {
+      vpc,
+      // REQUIRED: the instance runs a prompt-injectable agent, so its role
+      // must be capped by a permissions boundary you pre-create.
+      permissionsBoundaryArn:
+        'arn:aws:iam::123456789012:policy/kirocrew-ec2-boundary',
+      architecture: CrewArchitecture.ARM64,
+      instanceType: new ec2.InstanceType('m7g.2xlarge'),
+      // Pin a released tag for reproducible deploys — the default `main` drifts.
+      source: { kirocrewRef: 'v0.8.0' },
+      // Off-box backup: grants scoped write + installs a daily snapshot timer.
+      backupBucket: backup,
+      backupSchedule: 'daily',
+    });
+  }
+}
+
+const app = new App();
+new CrewStack(app, 'RemoteCrew', {
+  env: { account: '123456789012', region: 'eu-west-2' },
+});
+app.synth();
+```
+
+### 3. Deploy through your pipeline
+
+This is a plain CDK stack — deploy it however you deploy everything else
+(a CDK Pipelines / agentl stage, or `cdk deploy` from a keyless-OIDC CI job).
+The `WaitCondition` blocks stack completion until the gateway is actually
+serving, so a green deploy means a live crew (and a failed bootstrap rolls the
+stack back with the setup-log tail in the failure reason).
+
+```bash
+cdk deploy RemoteCrew
+```
+
+### 4. Connect
+
+Access is **SSM-only** — no inbound ports. Open a port-forward to the
+loopback dashboard and browse `http://127.0.0.1:5476`:
+
+```bash
+# The construct exports the instance id under a stable name derived from the
+# stackTag (default 'kirocrew'): kirocrew-<stackTag>-instance-id
+INSTANCE_ID=$(aws cloudformation list-exports \
+  --query "Exports[?Name=='kirocrew-kirocrew-instance-id'].Value" --output text)
+
+aws ssm start-session --target "$INSTANCE_ID" \
+  --document-name AWS-StartPortForwardingSession \
+  --parameters '{"portNumber":["5476"],"localPortNumber":["5476"]}'
+```
+
+(Or use the upstream `kirocrew cloud connect`, which mints the dashboard token
+on the box and opens the tunnel for you.)
+
+### 5. Verify backup
+
+The daily timer pushes a redaction-scrubbed snapshot to the backup bucket. Fire
+one immediately and confirm it landed:
+
+```bash
+# On the instance (via SSM Session Manager):
+sudo systemctl start kirocrew-backup.service
+sudo journalctl -u kirocrew-backup.service --no-pager | tail
+
+# From your workstation — the stable key a replacement instance restores from:
+aws s3 ls "s3://<backup-bucket>/crew-snapshots/latest.tar"
+```
+
+To rebuild a **replacement** instance from backup, deploy a fresh `CrewStack`
+pointing at the same bucket, then on the new box run
+`sudo kirocrew-restore-from-s3` (pulls `latest.tar`, stops the gateway,
+restores in replace mode, restarts).
+
+> **Container crew instead of an instance?** See [Fargate lane](#fargate-lane)
+> below — swap `RemoteCrewInstance` for `FargateCrewBase` + `FargateCrew`.
+
+The sections below are the per-construct reference.
+
+## What it creates
+
+| Resource | Notes |
+|---|---|
+| IAM role + instance profile | `AmazonSSMManagedInstanceCore` + a **required permissions boundary**; scoped `s3:GetObject` only when an S3 source is used |
+| Security group | **No inbound** by default (SSM-only); optional `tcp/22` from `allowSshCidr` (≤ /16); optional webhook port from a single source SG via `webhookIngress`; IPv6 egress when `enableIpv6` |
+| EC2 instance | Amazon Linux 2023, arch-aware AMI, **IMDSv2 enforced**, **encrypted gp3** root |
+| WaitConditionHandle + WaitCondition | Blocks stack completion until the gateway is actually serving on the loopback dashboard port |
+
+## Security posture (preserved from upstream)
+
+- **SSM-only access.** No inbound rules unless you explicitly pass `allowSshCidr`. Access is via SSM port-forward; the public DNS is diagnostics only.
+- **IMDSv2 required, hop limit 1.** KiroCrew runs a prompt-injectable agent that executes arbitrary tools — an SSRF/injection reaching the metadata endpoint must not be able to read the role's STS credentials via IMDSv1.
+- **Permissions boundary is mandatory** on the instance role.
+- **Node.js tarball is SHA-256-pinned** and verified before root extraction.
+- **Encrypted EBS root.**
+
+## Private dual-stack brain (55minutes posture)
+
+For an always-on brain that egresses over IPv6 with **no public IPv4**, is woken
+by the native KiroCrew webhook, and runs as an autopilot crew that never
+idle-closes, compose the additive props below. Everything here is optional and
+defaults off — omit it all and you get the SSM-only public-subnet box above.
+
+```ts
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { RemoteCrewInstance, CrewArchitecture } from '@raindancers/raindancers-crew';
+
+// vpc: a dual-stack VPC whose private subnets carry IPv6 CIDRs and route
+//      ::/0 to an Egress-Only Internet Gateway (see "What stays yours" below).
+// ingestLambdaSg: the SG of the consumer's ingest Lambda / reverse proxy —
+//      imported, this construct never creates it.
+new RemoteCrewInstance(this, 'Brain', {
+  vpc,
+  permissionsBoundaryArn:
+    'arn:aws:iam::123456789012:policy/kirocrew-ec2-boundary',
+  architecture: CrewArchitecture.ARM64,
+  source: { kirocrewRef: 'v0.8.0' },
+
+  // Private + dual-stack: IPv6 egress, no public IPv4.
+  vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
+  associatePublicIp: false,
+  enableIpv6: true,
+
+  // Webhook reach from ONE source SG only (never a CIDR), authenticated by a
+  // Bearer token fetched from Secrets Manager at boot (written to config.json
+  // as hooks.webhook_token; the instance role gets GetSecretValue on this ARN).
+  webhookIngress: { source: ingestLambdaSg },
+  webhookTokenSecretArn:
+    'arn:aws:secretsmanager:eu-west-2:123456789012:secret:kc/webhook-token-AbCdEf',
+
+  // Always-on: autopilot + never idle-close.
+  crewRuntime: { autopilot: true, disableIdleClose: true },
+});
+```
+
+### What stays yours (this construct provisions none of it)
+
+`RemoteCrewInstance` consumes an `IVpc` and provisions no routing, so these live
+in your VPC / app, not the library:
+
+- **Egress-Only Internet Gateway** and the `::/0` IPv6 egress route — the VPC's
+  concern. `enableIpv6` assigns the instance an IPv6 address and opens IPv6
+  egress on its SG, but the route to the internet is yours.
+- **fck-nat (or managed NAT)** for any IPv4 egress you still need.
+- **The ingest Lambda and its security group** — you build it and pass its SG as
+  `webhookIngress.source`. The construct only accepts it.
+- **Routable exposure of the webhook.** The KiroCrew gateway binds `127.0.0.1`
+  only (it has no routable listener), so `webhookIngress` opens the SG but a
+  **consumer-owned reverse proxy or SSH tunnel on the box** is what actually
+  forwards `POST /api/hooks/agent` from the source SG to the loopback gateway.
+  The dashboard stays loopback/SSM-only regardless.
+
+## Connecting
+
+`RemoteCrewInstance` provisions the box; **connection stays an operator action** (it is inherently imperative — mint a short-lived token on the instance and open an SSM port-forward). Use the upstream `kirocrew cloud connect` against the deployed instance id, or your own SSM `start-session` / port-forward wrapper.
+
+## Fargate lane
+
+For a container-based crew there are two sibling constructs, mirroring the upstream `kirocrew-fargate-base` + `kirocrew-fargate-crew` split:
+
+- **`FargateCrewBase`** — one per account/region: the ECS cluster crew tasks run on plus an egress-only (no-inbound) task security group. Deleting a crew must not delete the shared cluster, so this is separate.
+- **`FargateCrew`** — one per crew: the execution role (secret read scoped to `kirocrew/crew/<crew>/*`, log write, optional private-ECR pull), the **zero-policy task role** (the running container's blast radius — it must never gain `secretsmanager:GetSecretValue`), and the crew's log group. All names are derived from the crew name.
+
+```ts
+import { FargateCrewBase, FargateCrew } from '@raindancers/raindancers-crew';
+
+const base = new FargateCrewBase(this, 'CrewBase', { vpc });
+new FargateCrew(this, 'Crew', {
+  crew: 'fiftyfive',
+  // permissionsBoundaryArn: '...',  // optional until the shared boundary creator lands
+  // ecrRepositoryArn: '...',        // only for a private image; public registry needs no grant
+});
+```
+
+Security invariants preserved from upstream: task role has no policies and never reads secrets; execution-role secret read is crew-scoped with individually-listed actions (no prefix wildcards); both assume-role trusts carry an `aws:SourceAccount` condition. The permissions boundary is **optional** here (a declared degraded mode) because no creator for the crew boundary exists yet — unlike the EC2 lane, where it is mandatory.
+
+**EC2 vs Fargate:** EC2 gives a persistent box with local disk (the crew's memory/knowledge DBs live on the instance) and is the native launcher's default; Fargate is more ephemeral and expects external persistence. For a remote crew that remembers across sessions, EC2 is usually the better fit.
+
+## Backing up the crew's learnings
+
+A remote crew's value is its accumulated memory, lessons, and knowledge — which on the EC2 lane live on the instance's local disk. KiroCrew's built-in backup (`kirocrew snapshot`) produces a redaction-scrubbed bundle (the signing key, `.env`, and execution logs never ship), but writes it **locally** — so it survives corruption, not instance loss. These constructs add the missing **off-box durability**.
+
+`CrewBackupBucket` provisions a hardened destination: SSE-KMS (rotating key), all public access blocked, TLS-only, **versioned**, with a lifecycle rule expiring stale noncurrent versions. Bucket and key `RETAIN` on stack delete, so the backups outlive a teardown.
+
+```ts
+import { CrewBackupBucket, RemoteCrewInstance } from '@raindancers/raindancers-crew';
+
+const backup = new CrewBackupBucket(this, 'CrewBackup');
+
+new RemoteCrewInstance(this, 'Crew', {
+  vpc,
+  permissionsBoundaryArn: '...',
+  backupBucket: backup,          // grants scoped write + installs a daily timer
+  backupSchedule: 'daily',       // systemd OnCalendar
+});
+```
+
+On the **EC2 lane** this grants the instance role scoped write, installs a **systemd timer** that runs `kirocrew snapshot --purpose backup` and uploads the newest bundle to S3 (a timestamped key for history plus a stable `latest.tar`), and installs a `kirocrew-restore-from-s3` helper. On the **Fargate lane**, pass the same bucket to `FargateCrew` — it grants the **task role** (the running container) write, since the container runs its own snapshot push.
+
+### Restore (rebuilding a replacement crew)
+
+`kirocrew restore <bundle> --mode replace|merge`:
+
+- **replace** clears the target's memory/knowledge trees and rebuilds them from the bundle (the knowledge DB and memory stores are replaced wholesale, not row-merged). Restore validates database integrity and refuses a truncated bundle; `sel_hmac.key` is regenerated (not restored). Use on a fresh replacement instance.
+- **merge** layers the bundle onto existing state without clearing. Use to seed a crew you want to keep.
+
+On an EC2 instance provisioned with a backup bucket, `sudo kirocrew-restore-from-s3` pulls `latest.tar`, stops the gateway, restores in **replace** mode, and restarts — a one-command rebuild.
+
+## License
+
+Apache-2.0

package/lib/crew-backup-bucket.d.ts

@@ -0,0 +1,62 @@
+import { RemovalPolicy } from 'aws-cdk-lib';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as kms from 'aws-cdk-lib/aws-kms';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import { Construct } from 'constructs';
+import { ICrewBackupBucket } from './remote-crew-instance-props';
+/**
+ * Properties for {@link CrewBackupBucket}.
+ */
+export interface CrewBackupBucketProps {
+    /**
+     * Explicit bucket name. Omit to let CloudFormation generate one.
+     *
+     * @default - CloudFormation-generated
+     */
+    readonly bucketName?: string;
+    /**
+     * Days after which a NONCURRENT snapshot version is expired. Current
+     * versions are always kept. Set 0 to keep all versions forever.
+     *
+     * @default 90
+     */
+    readonly noncurrentVersionExpirationDays?: number;
+    /**
+     * What happens to the bucket when the stack is destroyed. Defaults to
+     * RETAIN — the whole point is that the crew's learnings outlive the
+     * instance, so the backup must outlive a stack teardown too.
+     *
+     * @default RemovalPolicy.RETAIN
+     */
+    readonly removalPolicy?: RemovalPolicy;
+}
+/**
+ * A hardened S3 bucket for KiroCrew snapshot backups.
+ *
+ * The snapshot bundle produced by `kirocrew snapshot --purpose backup` is
+ * already redaction-scrubbed (the signing key, `.env`, and execution logs
+ * never ship), so this stores portable crew state, not raw secrets. The bucket
+ * is nonetheless locked down as if it did: SSE-KMS at rest, all public access
+ * blocked, TLS-only access, versioned so an overwrite cannot destroy history,
+ * and a lifecycle rule that expires stale noncurrent versions.
+ *
+ * Use {@link grantWrite} to let an instance/task role push snapshots, and
+ * {@link grantRead} to let a replacement instance pull them for restore.
+ */
+export declare class CrewBackupBucket extends Construct implements ICrewBackupBucket {
+    /** The backup bucket. */
+    readonly bucket: s3.IBucket;
+    /** The KMS key encrypting the bucket. */
+    readonly key: kms.Key;
+    constructor(scope: Construct, id: string, props?: CrewBackupBucketProps);
+    /**
+     * Grant a principal permission to WRITE snapshots (and the KMS encrypt it
+     * needs). Used by the crew instance/task role that pushes backups.
+     */
+    grantWrite(grantee: iam.IGrantable): void;
+    /**
+     * Grant a principal permission to READ snapshots (and the KMS decrypt it
+     * needs). Used by a replacement instance restoring from backup.
+     */
+    grantRead(grantee: iam.IGrantable): void;
+}

package/lib/crew-backup-bucket.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrewBackupBucket = void 0;
+const JSII_RTTI_SYMBOL_1 = Symbol.for("jsii.rtti");
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const kms = __importStar(require("aws-cdk-lib/aws-kms"));
+const s3 = __importStar(require("aws-cdk-lib/aws-s3"));
+const constructs_1 = require("constructs");
+/**
+ * A hardened S3 bucket for KiroCrew snapshot backups.
+ *
+ * The snapshot bundle produced by `kirocrew snapshot --purpose backup` is
+ * already redaction-scrubbed (the signing key, `.env`, and execution logs
+ * never ship), so this stores portable crew state, not raw secrets. The bucket
+ * is nonetheless locked down as if it did: SSE-KMS at rest, all public access
+ * blocked, TLS-only access, versioned so an overwrite cannot destroy history,
+ * and a lifecycle rule that expires stale noncurrent versions.
+ *
+ * Use {@link grantWrite} to let an instance/task role push snapshots, and
+ * {@link grantRead} to let a replacement instance pull them for restore.
+ */
+class CrewBackupBucket extends constructs_1.Construct {
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@raindancers/raindancers-crew.CrewBackupBucket", version: "0.0.0" };
+    /** The backup bucket. */
+    bucket;
+    /** The KMS key encrypting the bucket. */
+    key;
+    constructor(scope, id, props = {}) {
+        super(scope, id);
+        this.key = new kms.Key(this, 'Key', {
+            description: 'KiroCrew snapshot backup bucket encryption key',
+            enableKeyRotation: true,
+            removalPolicy: props.removalPolicy ?? aws_cdk_lib_1.RemovalPolicy.RETAIN,
+        });
+        const noncurrentDays = props.noncurrentVersionExpirationDays ?? 90;
+        this.bucket = new s3.Bucket(this, 'Bucket', {
+            bucketName: props.bucketName,
+            encryption: s3.BucketEncryption.KMS,
+            encryptionKey: this.key,
+            bucketKeyEnabled: true,
+            blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+            enforceSSL: true,
+            versioned: true,
+            removalPolicy: props.removalPolicy ?? aws_cdk_lib_1.RemovalPolicy.RETAIN,
+            lifecycleRules: noncurrentDays > 0
+                ? [
+                    {
+                        // Keep current snapshots forever; expire superseded versions so
+                        // the bucket does not grow without bound.
+                        noncurrentVersionExpiration: aws_cdk_lib_1.Duration.days(noncurrentDays),
+                        abortIncompleteMultipartUploadAfter: aws_cdk_lib_1.Duration.days(7),
+                    },
+                ]
+                : undefined,
+        });
+    }
+    /**
+     * Grant a principal permission to WRITE snapshots (and the KMS encrypt it
+     * needs). Used by the crew instance/task role that pushes backups.
+     */
+    grantWrite(grantee) {
+        this.bucket.grantWrite(grantee);
+        this.key.grantEncryptDecrypt(grantee);
+    }
+    /**
+     * Grant a principal permission to READ snapshots (and the KMS decrypt it
+     * needs). Used by a replacement instance restoring from backup.
+     */
+    grantRead(grantee) {
+        this.bucket.grantRead(grantee);
+        this.key.grantDecrypt(grantee);
+    }
+}
+exports.CrewBackupBucket = CrewBackupBucket;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3Jldy1iYWNrdXAtYnVja2V0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NyZXctYmFja3VwLWJ1Y2tldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBQUEsNkNBQXNEO0FBRXRELHlEQUEyQztBQUMzQyx1REFBeUM7QUFDekMsMkNBQXVDO0FBZ0N2Qzs7Ozs7Ozs7Ozs7O0dBWUc7QUFDSCxNQUFhLGdCQUFpQixTQUFRLHNCQUFTOztJQUM3Qyx5QkFBeUI7SUFDVCxNQUFNLENBQWE7SUFDbkMseUNBQXlDO0lBQ3pCLEdBQUcsQ0FBVTtJQUU3QixZQUFZLEtBQWdCLEVBQUUsRUFBVSxFQUFFLFFBQStCLEVBQUU7UUFDekUsS0FBSyxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsQ0FBQztRQUVqQixJQUFJLENBQUMsR0FBRyxHQUFHLElBQUksR0FBRyxDQUFDLEdBQUcsQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFO1lBQ2xDLFdBQVcsRUFBRSxnREFBZ0Q7WUFDN0QsaUJBQWlCLEVBQUUsSUFBSTtZQUN2QixhQUFhLEVBQUUsS0FBSyxDQUFDLGFBQWEsSUFBSSwyQkFBYSxDQUFDLE1BQU07U0FDM0QsQ0FBQyxDQUFDO1FBRUgsTUFBTSxjQUFjLEdBQUcsS0FBSyxDQUFDLCtCQUErQixJQUFJLEVBQUUsQ0FBQztRQUVuRSxJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksRUFBRSxDQUFDLE1BQU0sQ0FBQyxJQUFJLEVBQUUsUUFBUSxFQUFFO1lBQzFDLFVBQVUsRUFBRSxLQUFLLENBQUMsVUFBVTtZQUM1QixVQUFVLEVBQUUsRUFBRSxDQUFDLGdCQUFnQixDQUFDLEdBQUc7WUFDbkMsYUFBYSxFQUFFLElBQUksQ0FBQyxHQUFHO1lBQ3ZCLGdCQUFnQixFQUFFLElBQUk7WUFDdEIsaUJBQWlCLEVBQUUsRUFBRSxDQUFDLGlCQUFpQixDQUFDLFNBQVM7WUFDakQsVUFBVSxFQUFFLElBQUk7WUFDaEIsU0FBUyxFQUFFLElBQUk7WUFDZixhQUFhLEVBQUUsS0FBSyxDQUFDLGFBQWEsSUFBSSwyQkFBYSxDQUFDLE1BQU07WUFDMUQsY0FBYyxFQUNaLGNBQWMsR0FBRyxDQUFDO2dCQUNoQixDQUFDLENBQUM7b0JBQ0E7d0JBQ0UsZ0VBQWdFO3dCQUNoRSwwQ0FBMEM7d0JBQzFDLDJCQUEyQixFQUFFLHNCQUFRLENBQUMsSUFBSSxDQUFDLGNBQWMsQ0FBQzt3QkFDMUQsbUNBQW1DLEVBQUUsc0JBQVEsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO3FCQUN0RDtpQkFDRjtnQkFDRCxDQUFDLENBQUMsU0FBUztTQUNoQixDQUFDLENBQUM7SUFDTCxDQUFDO0lBRUQ7OztPQUdHO0lBQ0ksVUFBVSxDQUFDLE9BQXVCO1FBQ3ZDLElBQUksQ0FBQyxNQUFNLENBQUMsVUFBVSxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBQ2hDLElBQUksQ0FBQyxHQUFHLENBQUMsbUJBQW1CLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDeEMsQ0FBQztJQUVEOzs7T0FHRztJQUNJLFNBQVMsQ0FBQyxPQUF1QjtRQUN0QyxJQUFJLENBQUMsTUFBTSxDQUFDLFNBQVMsQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUMvQixJQUFJLENBQUMsR0FBRyxDQUFDLFlBQVksQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNqQyxDQUFDOztBQXhESCw0Q0F5REMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBEdXJhdGlvbiwgUmVtb3ZhbFBvbGljeSB9IGZyb20gJ2F3cy1jZGstbGliJztcbmltcG9ydCAqIGFzIGlhbSBmcm9tICdhd3MtY2RrLWxpYi9hd3MtaWFtJztcbmltcG9ydCAqIGFzIGttcyBmcm9tICdhd3MtY2RrLWxpYi9hd3Mta21zJztcbmltcG9ydCAqIGFzIHMzIGZyb20gJ2F3cy1jZGstbGliL2F3cy1zMyc7XG5pbXBvcnQgeyBDb25zdHJ1Y3QgfSBmcm9tICdjb25zdHJ1Y3RzJztcbmltcG9ydCB7IElDcmV3QmFja3VwQnVja2V0IH0gZnJvbSAnLi9yZW1vdGUtY3Jldy1pbnN0YW5jZS1wcm9wcyc7XG5cbi8qKlxuICogUHJvcGVydGllcyBmb3Ige0BsaW5rIENyZXdCYWNrdXBCdWNrZXR9LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIENyZXdCYWNrdXBCdWNrZXRQcm9wcyB7XG4gIC8qKlxuICAgKiBFeHBsaWNpdCBidWNrZXQgbmFtZS4gT21pdCB0byBsZXQgQ2xvdWRGb3JtYXRpb24gZ2VuZXJhdGUgb25lLlxuICAgKlxuICAgKiBAZGVmYXVsdCAtIENsb3VkRm9ybWF0aW9uLWdlbmVyYXRlZFxuICAgKi9cbiAgcmVhZG9ubHkgYnVja2V0TmFtZT86IHN0cmluZztcblxuICAvKipcbiAgICogRGF5cyBhZnRlciB3aGljaCBhIE5PTkNVUlJFTlQgc25hcHNob3QgdmVyc2lvbiBpcyBleHBpcmVkLiBDdXJyZW50XG4gICAqIHZlcnNpb25zIGFyZSBhbHdheXMga2VwdC4gU2V0IDAgdG8ga2VlcCBhbGwgdmVyc2lvbnMgZm9yZXZlci5cbiAgICpcbiAgICogQGRlZmF1bHQgOTBcbiAgICovXG4gIHJlYWRvbmx5IG5vbmN1cnJlbnRWZXJzaW9uRXhwaXJhdGlvbkRheXM/OiBudW1iZXI7XG5cbiAgLyoqXG4gICAqIFdoYXQgaGFwcGVucyB0byB0aGUgYnVja2V0IHdoZW4gdGhlIHN0YWNrIGlzIGRlc3Ryb3llZC4gRGVmYXVsdHMgdG9cbiAgICogUkVUQUlOIOKAlCB0aGUgd2hvbGUgcG9pbnQgaXMgdGhhdCB0aGUgY3JldydzIGxlYXJuaW5ncyBvdXRsaXZlIHRoZVxuICAgKiBpbnN0YW5jZSwgc28gdGhlIGJhY2t1cCBtdXN0IG91dGxpdmUgYSBzdGFjayB0ZWFyZG93biB0b28uXG4gICAqXG4gICAqIEBkZWZhdWx0IFJlbW92YWxQb2xpY3kuUkVUQUlOXG4gICAqL1xuICByZWFkb25seSByZW1vdmFsUG9saWN5PzogUmVtb3ZhbFBvbGljeTtcbn1cblxuLyoqXG4gKiBBIGhhcmRlbmVkIFMzIGJ1Y2tldCBmb3IgS2lyb0NyZXcgc25hcHNob3QgYmFja3Vwcy5cbiAqXG4gKiBUaGUgc25hcHNob3QgYnVuZGxlIHByb2R1Y2VkIGJ5IGBraXJvY3JldyBzbmFwc2hvdCAtLXB1cnBvc2UgYmFja3VwYCBpc1xuICogYWxyZWFkeSByZWRhY3Rpb24tc2NydWJiZWQgKHRoZSBzaWduaW5nIGtleSwgYC5lbnZgLCBhbmQgZXhlY3V0aW9uIGxvZ3NcbiAqIG5ldmVyIHNoaXApLCBzbyB0aGlzIHN0b3JlcyBwb3J0YWJsZSBjcmV3IHN0YXRlLCBub3QgcmF3IHNlY3JldHMuIFRoZSBidWNrZXRcbiAqIGlzIG5vbmV0aGVsZXNzIGxvY2tlZCBkb3duIGFzIGlmIGl0IGRpZDogU1NFLUtNUyBhdCByZXN0LCBhbGwgcHVibGljIGFjY2Vzc1xuICogYmxvY2tlZCwgVExTLW9ubHkgYWNjZXNzLCB2ZXJzaW9uZWQgc28gYW4gb3ZlcndyaXRlIGNhbm5vdCBkZXN0cm95IGhpc3RvcnksXG4gKiBhbmQgYSBsaWZlY3ljbGUgcnVsZSB0aGF0IGV4cGlyZXMgc3RhbGUgbm9uY3VycmVudCB2ZXJzaW9ucy5cbiAqXG4gKiBVc2Uge0BsaW5rIGdyYW50V3JpdGV9IHRvIGxldCBhbiBpbnN0YW5jZS90YXNrIHJvbGUgcHVzaCBzbmFwc2hvdHMsIGFuZFxuICoge0BsaW5rIGdyYW50UmVhZH0gdG8gbGV0IGEgcmVwbGFjZW1lbnQgaW5zdGFuY2UgcHVsbCB0aGVtIGZvciByZXN0b3JlLlxuICovXG5leHBvcnQgY2xhc3MgQ3Jld0JhY2t1cEJ1Y2tldCBleHRlbmRzIENvbnN0cnVjdCBpbXBsZW1lbnRzIElDcmV3QmFja3VwQnVja2V0IHtcbiAgLyoqIFRoZSBiYWNrdXAgYnVja2V0LiAqL1xuICBwdWJsaWMgcmVhZG9ubHkgYnVja2V0OiBzMy5JQnVja2V0O1xuICAvKiogVGhlIEtNUyBrZXkgZW5jcnlwdGluZyB0aGUgYnVja2V0LiAqL1xuICBwdWJsaWMgcmVhZG9ubHkga2V5OiBrbXMuS2V5O1xuXG4gIGNvbnN0cnVjdG9yKHNjb3BlOiBDb25zdHJ1Y3QsIGlkOiBzdHJpbmcsIHByb3BzOiBDcmV3QmFja3VwQnVja2V0UHJvcHMgPSB7fSkge1xuICAgIHN1cGVyKHNjb3BlLCBpZCk7XG5cbiAgICB0aGlzLmtleSA9IG5ldyBrbXMuS2V5KHRoaXMsICdLZXknLCB7XG4gICAgICBkZXNjcmlwdGlvbjogJ0tpcm9DcmV3IHNuYXBzaG90IGJhY2t1cCBidWNrZXQgZW5jcnlwdGlvbiBrZXknLFxuICAgICAgZW5hYmxlS2V5Um90YXRpb246IHRydWUsXG4gICAgICByZW1vdmFsUG9saWN5OiBwcm9wcy5yZW1vdmFsUG9saWN5ID8/IFJlbW92YWxQb2xpY3kuUkVUQUlOLFxuICAgIH0pO1xuXG4gICAgY29uc3Qgbm9uY3VycmVudERheXMgPSBwcm9wcy5ub25jdXJyZW50VmVyc2lvbkV4cGlyYXRpb25EYXlzID8/IDkwO1xuXG4gICAgdGhpcy5idWNrZXQgPSBuZXcgczMuQnVja2V0KHRoaXMsICdCdWNrZXQnLCB7XG4gICAgICBidWNrZXROYW1lOiBwcm9wcy5idWNrZXROYW1lLFxuICAgICAgZW5jcnlwdGlvbjogczMuQnVja2V0RW5jcnlwdGlvbi5LTVMsXG4gICAgICBlbmNyeXB0aW9uS2V5OiB0aGlzLmtleSxcbiAgICAgIGJ1Y2tldEtleUVuYWJsZWQ6IHRydWUsXG4gICAgICBibG9ja1B1YmxpY0FjY2VzczogczMuQmxvY2tQdWJsaWNBY2Nlc3MuQkxPQ0tfQUxMLFxuICAgICAgZW5mb3JjZVNTTDogdHJ1ZSxcbiAgICAgIHZlcnNpb25lZDogdHJ1ZSxcbiAgICAgIHJlbW92YWxQb2xpY3k6IHByb3BzLnJlbW92YWxQb2xpY3kgPz8gUmVtb3ZhbFBvbGljeS5SRVRBSU4sXG4gICAgICBsaWZlY3ljbGVSdWxlczpcbiAgICAgICAgbm9uY3VycmVudERheXMgPiAwXG4gICAgICAgICAgPyBbXG4gICAgICAgICAgICB7XG4gICAgICAgICAgICAgIC8vIEtlZXAgY3VycmVudCBzbmFwc2hvdHMgZm9yZXZlcjsgZXhwaXJlIHN1cGVyc2VkZWQgdmVyc2lvbnMgc29cbiAgICAgICAgICAgICAgLy8gdGhlIGJ1Y2tldCBkb2VzIG5vdCBncm93IHdpdGhvdXQgYm91bmQuXG4gICAgICAgICAgICAgIG5vbmN1cnJlbnRWZXJzaW9uRXhwaXJhdGlvbjogRHVyYXRpb24uZGF5cyhub25jdXJyZW50RGF5cyksXG4gICAgICAgICAgICAgIGFib3J0SW5jb21wbGV0ZU11bHRpcGFydFVwbG9hZEFmdGVyOiBEdXJhdGlvbi5kYXlzKDcpLFxuICAgICAgICAgICAgfSxcbiAgICAgICAgICBdXG4gICAgICAgICAgOiB1bmRlZmluZWQsXG4gICAgfSk7XG4gIH1cblxuICAvKipcbiAgICogR3JhbnQgYSBwcmluY2lwYWwgcGVybWlzc2lvbiB0byBXUklURSBzbmFwc2hvdHMgKGFuZCB0aGUgS01TIGVuY3J5cHQgaXRcbiAgICogbmVlZHMpLiBVc2VkIGJ5IHRoZSBjcmV3IGluc3RhbmNlL3Rhc2sgcm9sZSB0aGF0IHB1c2hlcyBiYWNrdXBzLlxuICAgKi9cbiAgcHVibGljIGdyYW50V3JpdGUoZ3JhbnRlZTogaWFtLklHcmFudGFibGUpOiB2b2lkIHtcbiAgICB0aGlzLmJ1Y2tldC5ncmFudFdyaXRlKGdyYW50ZWUpO1xuICAgIHRoaXMua2V5LmdyYW50RW5jcnlwdERlY3J5cHQoZ3JhbnRlZSk7XG4gIH1cblxuICAvKipcbiAgICogR3JhbnQgYSBwcmluY2lwYWwgcGVybWlzc2lvbiB0byBSRUFEIHNuYXBzaG90cyAoYW5kIHRoZSBLTVMgZGVjcnlwdCBpdFxuICAgKiBuZWVkcykuIFVzZWQgYnkgYSByZXBsYWNlbWVudCBpbnN0YW5jZSByZXN0b3JpbmcgZnJvbSBiYWNrdXAuXG4gICAqL1xuICBwdWJsaWMgZ3JhbnRSZWFkKGdyYW50ZWU6IGlhbS5JR3JhbnRhYmxlKTogdm9pZCB7XG4gICAgdGhpcy5idWNrZXQuZ3JhbnRSZWFkKGdyYW50ZWUpO1xuICAgIHRoaXMua2V5LmdyYW50RGVjcnlwdChncmFudGVlKTtcbiAgfVxufVxuIl19