Skip to content

feat(shared-crew): share a Crew over AWS SSM with an invite-only link - #29923

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
feat/shared-crew-ssm
Nov 6, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
feat/shared-crew-ssm

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An owner can share a Crew that runs on an AWS machine with teammates who reach it through AWS Systems Manager (SSM), each one named and revocable, with the same parts Shared Crew gives Tailscale.

Today only Tailscale can name a teammate. An SSM Session Manager port forward reaches the gateway as a plain loopback connection with no forwarding header, which is exactly what the owner's own browser looks like, and the guide says such teammates are "credited to whoever runs the Crew".

Why it matters

Teams that run a Crew on EC2 already have SSM access control and often cannot use Tailscale. Without this, sharing there means handing out the owner's dashboard token, which makes every teammate the owner.

Not a goal

  • Reading the AWS caller's identity. Session Manager does not forward it; the owner's invite names the person.
  • An invite expiry or an IAM policy generator. A link stays valid until removed; the guide says how to scope IAM.
  • A new invite flow. SSM is a tab of the one Invite dialog, not a card.
  • Governance pinning for SSM, or hosting the SSM port on the headless --slack-only API server.

What changed (motivation → approach → change)

Merge order: #29592 (People single invite) has merged, so this PR is the SSM commit alone on main. It depends on #29609 (guest permissions) for one follow-up: once that lands, routes_ssm.api_revoke calls its pause_revoked_schedules(principal_ids) so removing a person pauses the schedules they created (the helper is not copied here). The remove-confirmation copy is People's shared key. Issue: #29552.

Approach. A forwarded connection cannot be told from the owner's by its address, so the port says it: with dashboard.shared_crew.ssm on, the gateway also binds 127.0.0.1:<ssm_port> (default 5477). Every request on that port is decided in dashboard/ssm_gate.py and never enters the token flow. Only a Crew invite opens it; the owner's token, app tokens and the internal secret mean nothing there, so a forwarded connection is never the owner.

Parity with Tailscale:

Tailscale gives SSM gets
Status and availability ssm setup path and GET /api/shared-crew/ssm: state, reason, node id, region
Share setting ssm and ssm_port in People > Advanced, off by default
Link to share the aws ssm start-session argument list plus http://localhost:<port>/?ssm_invite=…
Copyable invite message "Copy invite message" with the command, the link and the guide link
Identity of the person the invite id, with the owner's alias as the label (Provenance.SSM_INVITE)
Remove (revoke) the one RevokeControl: "Remove" on every non-owner row, joined or not, Tailscale or SSM; open connections close within 15 s
First-share confirmation the same gate and one acknowledgement for both transports
Docs shared-crew.md, the remote-access guide, security, config and token-auth specs

Change. The node id comes from KIROCREW_SSM_TARGET or IMDSv2; nothing reads or writes AWS configuration and no process is started. Invites live in .vault/shared-crew-ssm/ as a SHA-256 of the secret plus an alias, with a joined flag set on first use. origin.is_direct_local_request answers False for an SSM request, _caller_bounds lends it no bearer-link lifetime, and test_ssm_loopback_trust_sites.py lists every peer-address trust site so a new one must be classified. In the dashboard, SSM is a tab in the Invite dialog, shown only when Tailscale invites are on too; unopened invites are Not joined rows and a joined person's row carries the Remove control.

Files: config-baseline.json (regenerated), src/kiro_crew/change_card_catalog_kinds.py, src/kiro_crew/config/sections_shared_crew.py, src/kiro_crew/shared_crew/access.py, src/kiro_crew/shared_crew/access_set.py, src/kiro_crew/shared_crew/collaborators.py, src/kiro_crew/shared_crew/contracts.py, src/kiro_crew/shared_crew/identity.py, src/kiro_crew/shared_crew/routes_ssm.py, src/kiro_crew/shared_crew/ssm.py, src/kiro_crew/shared_crew/ssm_invites.py, website/src/api/client/sharedCrew.ts, website/src/api/sharedCrew.ts, website/src/api/sharedCrewSsm.ts, website/src/api/sharedCrewUi.ts, website/src/i18n/en.context.json, website/src/test/ApiClient.refactor.surface.test.ts. The People commit (#29592) is the other half of the diff: src/kiro_crew/shared_crew/routes_invites.py, src/kiro_crew/shared_crew/tailscale_invites.py, website/src/api/sharedCrewInvites.ts, website/src/api/sharedCrewUi.test.ts, website/src/components/SharedCrewReadFailures.test.tsx, website/src/i18n/sharedCrewHonestCopy.test.ts, website/src/test/settingsCoverage.test.ts.

Judgment calls. A separate port rather than a header or token check, because loopback gives nothing to check. KIROCREW_SSM_TARGET for hosts without IMDS, instead of another config field. The confirm text of Remove is the People wording for both transports. The owner-side AWS CLI check was dropped from the UI: the teammate's machine needs the tools, so the invite message ends with the guide link.

Accepted trade-offs. No expiry: a link is permanent until removed, one link is one identity, and a removal takes up to 15 s to close an open connection. The mc_ssm cookie is host-scoped, so a browser sends it to any localhost port (cookies are not port-scoped); it is the invite, so treat the link like a password. A teammate with a Session Manager shell document already has host access; the guide tells owners to scope IAM to a custom document with a fixed portNumber.

Backwards compatibility

Compatible: everything is off by default (ssm reads false unless a literal true); the only change to existing behaviour is that origin.is_direct_local_request and the bearer-link mint now refuse a request the SSM listener admitted, which no existing path produces.

Removes nothing: the guide sentence that credited SSM teammates to the owner described a path that still needs a dashboard token; it now points at the SSM link.

Tests

Proof: not provable -- other: a new transport with no fix to revert; the gate test is mutation-checked instead (below).

  • test/test_shared_crew_ssm.py runs the real token middleware on two real loopback sites. The owner's token, cookie, internal secret and both together on the SSM port are refused or never the owner, while the same token on the dashboard port is the owner (mutation-checked: removing the gate hook fails 7 tests). It also covers invites, revoke while a request is open, joined, and the first-share 409.
  • test/test_ssm_loopback_trust_sites.py pins the SSM refusal in every peer-address check and the bearer-mint refusal.
  • website/src/pages/settings/SsmInvite.test.tsx covers tabs, status reasons, the first-share dialog, rows, the same Remove wording, and no loss of a link on a late read or a tab switch.
  • Determinism: 20 repeats at -n0, 10 at -n 4 --dist loadgroup with sibling files, and one shuffled order (seed 7712), all green.
  • Local gates: black, isort, flake8, mypy, comment history, sync-io, feature map, docs lint, gen:ui, tsc, eslint, i18n check and render pass. Not green locally and not from this change: person_remove* Hindi register (from fix(shared-crew): one invite entry and one People row per person #29592), test:electron (environment), navLabels timeout (also on fix(shared-crew): one invite entry and one People row per person #29592), and the scoped-backend runner timed out, so related backend tests were run by node set instead (7,500 passed).

Manual verification

The gateway-start path (start_after_bind) and a live Session Manager forward were not run: this host is not an SSM node. Everything on the gate is exercised with real sockets in tests.

  • Not run on a real EC2 host: the instance-metadata read (ssm.read_imds, IMDSv2 token then instance id and region) is covered by fakes only. It fails closed to no_target, and KIROCREW_SSM_TARGET / KIROCREW_SSM_REGION bypass it. One run on EC2 with the ssm switch on and a teammate's aws ssm start-session is the remaining check.

The one change outside the SSM path: the Tailscale "Copy invite message" button now reads "Copy Tailscale invite" (copy icon), because the SSM tab has its own "Copy SSM invite" and the two copy different text; the owner asked for the two to be named by transport.

Screenshots / video

Captured from the current head with the shared-crew fixtures stubbed (temp-screenshots/ssm/capture.mjs).

Setup page before anything is turned on: Tailscale, AWS SSM ("Teammates in your AWS account. Needs SSM on this machine." and its guide link) and Kiro login:

Setup page before anything is turned on: Tailscale, AWS SSM ("Teammates in your AWS account. Needs SSM on this machine." and its guide link) and Kiro login

People, Advanced expanded: the switch is named for its result, "Let teammates join over AWS SSM", off:

People, Advanced expanded: the switch is named for its result, "Let teammates join over AWS SSM", off

Same switch on: the existing "changes need a restart" pill shows beside it and the help line says Invite then has an AWS SSM tab:

Same switch on: the existing "changes need a restart" pill shows beside it and the help line says Invite then has an AWS SSM tab

Invite dialog, Tailscale tab:

Invite dialog, Tailscale tab

Invite dialog, AWS SSM tab:

Invite dialog, AWS SSM tab

First link: the one-time Share this Crew? confirmation, worded for SSM:

First link: the one-time Share this Crew? confirmation, worded for SSM

A link just made: shown once, with one copy action that holds the link and the port-forward command (Copy SSM invite):

A link just made: shown once, with one copy action that holds the link and the port-forward command (Copy SSM invite)

A link just made, dark:

A link just made, dark

People list: a joined SSM person (Dana, with Remove) and an unopened SSM invite under Invites (Lee); the share card's button reads Copy Tailscale invite:

People list: a joined SSM person (Dana, with Remove) and an unopened SSM invite under Invites (Lee); the share card's button reads Copy Tailscale invite

Same list, dark:

Same list, dark

Remove on a joined person:

Remove on a joined person

Remove on an unopened SSM invite:

Remove on an unopened SSM invite

No SSM node found for this machine:

No SSM node found for this machine

The SSM status read fails: a notice with Try again on the People page, instead of the SSM controls vanishing:

The SSM status read fails: a notice with Try again on the People page, instead of the SSM controls vanishing

Related Issues

Closes #29552

Pattern harvest

Not generalizable: this adds a transport; the one reusable lesson, that a loopback peer address is not proof of the owner, is pinned by test_ssm_loopback_trust_sites.py.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 4, 2026 20:45
@bolichen97
bolichen97 requested a review from mbriones98 November 4, 2026 20:45
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 9f45f7bf9a0790325594bb9bae14665c461b7064 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: giving SSM its own port is the only signal a header-less loopback forward has, and the guest never enters the token flow.

Notes

  • Every check that trusts a loopback peer has to remember is_ssm_request, so safety depends on that list staying complete (test_ssm_loopback_trust_sites.py pins it). If one is missed, an SSM guest is treated as the machine's own user. Because of that, the next new trust site should go through is_direct_local_request and not call is_loopback(request.remote) directly.
  • The description's "Files" list leaves out the core hunks (dashboard/ssm_gate.py, token_auth.py, origin.py, security_middleware.py, cloud/ssm.py). The approach text does cover them, but a reviewer working from the list would miss the gate.

[DESIGN-REVIEWED] 9f45f7b

Description read

[DESCRIPTION-READ] 049babf7cf5aa6934ea42374d17f76424c05950bdf47e5c5c7e43d1170a859cb

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 9f45f7bf9a0790325594bb9bae14665c461b7064 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks. Fourteen screenshots cover every new control and state, and the blind reader read each primary control (AWS SSM tab, "Make link", "Copy SSM invite", the Advanced switch) correctly.

Notes

  • SsmReadError shows inviteErrorText('error'), which renders as "That did not work. Try again." (shot-14). It also hides the SSM invite rows and Dana's Remove button. The reader could not tell what failed and asked: "I don't know if Lee's invite was deleted." Use a dedicated key instead, such as "Could not load AWS SSM invites. Your invites are unchanged."
  • adv_ssm_help "Restart to turn this on." doesn't say what to restart, and the page offers no way to do it. The reader asked: "Restart what, the app or the computer? There's no restart button anywhere." Say what gets restarted, for example "Takes effect after Kiro Crew restarts.", or link the existing restart action.
  • SsmInviteRow reuses invite_link_row and ssm_not_copied ("Link not shown again"), but nothing shows which way each person joined. The reader asked whether "Shared on your tailnet" also covers SSM people. Add a small "AWS SSM" badge to SSM rows.

[UX-REVIEWED] 9f45f7b

Description read

[DESCRIPTION-READ] ca203b46414a01165c839f136f96d3c356585a4ef8eeafde62f4d8bd049e1df0

That sha256 names everything this verdict read: the PR description, plus the 17 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 9f45f7bf9a0790325594bb9bae14665c461b7064 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

One undeclared relabel of the existing Tailscale copy button; it is a note, not a blocker. Every other item is new SSM surface behind a flag that is off by default, or a refusal for SSM guests.

Notes

  • Item 9 — unjustified move: the existing Tailscale button changes from "invite_copy_message": "Copy invite message" to "invite_copy_tailscale": "Copy Tailscale invite", and its icon changes from MessageSquare to Copy. Nobody is named as failing to find it, and the description says the SSM button reads "Copy invite message", which the diff contradicts ("invite_copy_ssm": "Copy SSM invite"). Subtraction: keep invite_copy_message and MessageSquare for both transports and delete the invite_copy_tailscale and invite_copy_ssm keys.

What this change ships

Inventory (10 items) — 9 justified

Intent: an owner shares a Crew on EC2 with named, revocable teammates over SSM port forwarding instead of handing out the owner token. ADDITION.

  1. New People > Advanced toggle dashboard.shared_crew.ssm, off by default — justified
  2. A second loopback port (ssm_port, 5477) where only a Crew invite admits anyone — justified
  3. An SSM tab in the Invite dialog with the aws ssm start-session command and an invite link — justified
  4. Invites stored hashed with an alias; a joined teammate is named as that alias in People — justified
  5. Remove on SSM rows, both joined and not joined; open connections close within 15 s — justified
  6. SSM requests are refused as "local" by computer use, the updates channel, step-up, config and secret gates, and bearer-link minting — justified
  7. SSM guests see an empty Apps list — justified
  8. The host-canonicalization redirect is skipped on the SSM port — justified
  9. The Tailscale "Copy invite message" button is relabelled "Copy Tailscale invite" with a new icon — unjustified move, undeclared
  10. build_port_forward_argv gains a document parameter for a custom Session document — justified

[FIRST-PRINCIPLES-REVIEWED] 9f45f7b

Description read

[DESCRIPTION-READ] e0d2f6832f988c66de42cf92abb5fbb97c0f72c8968908db30338f6b997735cc

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 9f45f7bf9a0790325594bb9bae14665c461b7064 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9f45f7b

Verdict parsed from the review's SHA-scoped output markers for commit 9f45f7bf9a0790325594bb9bae14665c461b7064.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9f45f7bf9a0790325594bb9bae14665c461b7064 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 9f45f7bf9a0790325594bb9bae14665c461b7064 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9f45f7b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9f45f7bf9a0790325594bb9bae14665c461b7064 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 4, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 4, 2026 21:13
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from 99cc6e4 to 49f6a75 Compare November 4, 2026 22:42
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 4, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch 3 times, most recently from 84ea409 to d6e324e Compare November 4, 2026 22:46
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 4, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from d6e324e to 080ffb1 Compare November 4, 2026 23:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 4, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch 2 times, most recently from 0fc013d to 4eaa100 Compare November 5, 2026 00:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 5, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 5, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from 7edb9fd to 45fe6bd Compare November 5, 2026 06:00
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 5, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from 45fe6bd to 5890817 Compare November 5, 2026 06:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 5, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from 5890817 to c62c1c0 Compare November 5, 2026 07:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 5, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from c62c1c0 to 5da39f5 Compare November 5, 2026 08:05
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 5, 2026
@bolichen97
bolichen97 force-pushed the feat/shared-crew-ssm branch from 5da39f5 to 9a3b09a Compare November 5, 2026 08:59
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 5, 2026
# withholds a Strict cookie from the redirected request of a cross-site navigation, so
# the page it lands on would refuse the guest. Lax still holds back the cookie from
# cross-site POSTs and subresources; the origin allowlist covers writes as before.
response.set_cookie(cookie_name(request), credential, httponly=True, samesite="Lax", path="/")
# withholds a Strict cookie from the redirected request of a cross-site navigation, so
# the page it lands on would refuse the guest. Lax still holds back the cookie from
# cross-site POSTs and subresources; the origin allowlist covers writes as before.
response.set_cookie(cookie_name(request), credential, httponly=True, samesite="Lax", path="/")
@bolichen97

Copy link
Copy Markdown
Contributor Author

Disposition: UX lane, "Let teammates join over AWS SSM" switch (Settings > Advanced)

Owner ruling (Bolin), recorded here by the agent working this PR on Bolin's instruction. The current design of the switch stands. No further change to it on this PR.

Why: across four heads the UX lane asked for four different things about this one switch, and the later asks contradict the earlier ones.

  1. 48a670d454: rename the label to an outcome and add a help line.
  2. c62c1c0057: say what restarts, and link the setup row to the switch.
  3. 5da39f56a1: drop "gateway" from the copy, and add a pending state with a restart action.
  4. c5d4c7c615 / 3266e5fb8e: asked whether the switch restarts or the user does, which reverses ask 3.

Head 9a3b09a1ae passed with the same text that 5da39f56a1 had blocked.

What the switch does today: it reuses the existing restart pattern. dashboard.shared_crew.ssm is requiresRestart, so the existing SchemaRestartBadge pill sits beside it and the help line says "Restart to turn this on. Invite then has an AWS SSM tab." in all 12 locales. There is no settings-wide restart action to reuse, and building one is out of scope for this PR.

If the UX lane blocks only on this switch at the current head, the next comment is an /ai-review override ux that links back to this comment. Any other UX finding will be fixed, not overridden.

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

Verdict: NEEDS_OWNER. The code does what it says and I found no defect. Two security-design choices still need a maintainer decision, and nothing records one: issue #29552 is labelled parked, and docs/decisions holds no SSM entry.

Owner question, in two sentences: an enterprise that pins capabilities.tailnet_origin off has no matching switch to forbid SSM sharing, because SsmGate starts whenever ssm is on and no dashboard_origins policy refuses its two loopback origins. Should SSM sharing be behind a governance capability before it ships, and is it acceptable that a permanent, reusable bearer link with no expiry, which anyone holding it can open from any number of browsers, is the only thing standing in for a membership boundary?

What it does for users: an owner running a Crew on EC2 can share it with named, revocable teammates who reach it through an AWS Session Manager port forward, without handing out the owner's dashboard credential.

What I verified in source at this head

  • Who can mint or revoke an invite. All three routes in shared_crew/routes_ssm.py go through routes_invites._owner_refusal. They answer 404 without the preview and 404 while governance withdraws the SSM origins (routes_ssm.py:85-97). An SSM guest is subject ssm:, so is_owner_dashboard_request (source_providers.py:880-889) can never match the owner_id or the local-app and local-startup subjects.
  • How an invite is bound. The credential is <12-hex id>.<32 random URL-safe bytes>. Only a SHA-256 of the secret is stored, under .vault/shared-crew-ssm, owner-only (ssm_invites.py:93-110). The compare runs in constant time and does dummy work on a miss (ssm_invites.py:126-140). An invite can be used more than once and has no expiry. The PR states both, and they are a design choice, not a bug. Revoke deletes the record. The next request is refused, an open response is closed by the re-verify watcher within 15 s (ssm_gate.py:174-196), and the revoke route closes the person's dashboard sockets (routes_ssm.py:139-170). The store holds at most 64 invites.
  • What a guest can reach. ssm_gate.admit (ssm_gate.py:199-243) sets the same request keys as the tailnet direct listener (dashboard auth middleware, lines 316-321), plus the SSM marker. A guest therefore gets the same collaborator reach a Tailscale direct guest gets today. It also gets an empty Apps list (apps/routes_listing.py), it is never direct-local (origin.py:134), and it cannot mint a bearer link (_shared_access.py:218-224). Strict internal paths and any X-Internal-Secret header are refused before the invite is checked. A dashboard credential, an app credential or the internal secret on this port is ignored, because the hook runs ahead of the normal credential flow (dashboard auth middleware, lines 327-339).
  • Off by default and behind the preview. ssm defaults to false, and only a literal true turns it on (sections_shared_crew.py, SHARED_CREW_EXPOSURE_FLAGS). The gate ref is created only when the Shared Crew preview is on (server.py:1086-1093).
  • Bind address. The listener binds only 127.0.0.1:<ssm_port> and refuses the dashboard port (ssm_gate.py:268-308). SsmGate.owns keys on the local sockname, which must be loopback and on the SSM port (ssm_gate.py:69-86), so the request itself cannot claim to be SSM. The canonical-host redirect is skipped on this port, so the invite query never follows a redirect to another loopback family (security_middleware.py:572-594).
  • Where the credential can end up. The invite reaches the gateway once as ?ssm_invite=. It is stored in an HttpOnly, SameSite=Lax cookie, and the browser is sent to a 302 without the query, with Referrer-Policy: no-referrer and no-store. The auth audit records request.path without the query (the auth audit helper, _log_auth). The aiohttp access logger runs at INFO, under the root WARNING level set in cli_logging.py, so the request line never reaches gateway.log. The credential stays in the invitee's browser history, and because cookies are not port-scoped, the cookie is sent to every localhost port on the invitee's machine. The PR states both.

Tests and mutations

  • 219 passed across test_shared_crew_ssm.py, test_ssm_loopback_trust_sites.py, test_governance_remote_access_keys.py, test_shared_crew_access.py and test_shared_crew_advanced_settings_write.py. The full suite was not run.
  • Frontend: 137 passed in SsmInvite.test.tsx, TailscaleInvites.test.tsx and PeoplePanel.test.tsx.
  • Mutation 1, the invite check: I removed the secret-digest compare in ssm_invites.verify, so a known id with any secret is accepted. Two tests went red: test_an_invite_verifies_until_it_is_revoked_and_stores_only_a_hash and test_an_invite_reads_joined_once_someone_opens_it_and_names_their_person.
  • Mutation 2, the direct-local refusal: I dropped is_ssm_request from origin.is_direct_local_request. Two tests went red: test_an_ssm_request_is_never_direct_local[guest-mark] and test_an_ssm_request_is_never_direct_local[admitted-mark].
  • CI on this head: 85 checks succeeded, 11 were skipped and none failed. PR Readiness and both CodeBuild statuses are success. The merge-tree check against main is clean. The Design, UX, First Principles, Opus and GPT lanes all PASS on this head.
  • CodeQL flags "cookie built from user input" at ssm_gate.py:168. The cookie value is set only after it matches the issued shape and verifies against a live invite. The cookie name takes only digits from the Host port. I judge it a false positive.

What I did not run: a live Session Manager forward, IMDSv2 on a real EC2 host, and the gateway start path (start_after_bind). The PR says the same.

Follow-ups, non-blocking

  • Revoking an SSM person does not yet pause the schedules that person created. Their schedules keep running on this Crew until #29609 lands and api_revoke calls pause_revoked_schedules.
  • governance.md is unchanged. If SSM stays outside a capability pin, governance.md should say plainly that capabilities.tailnet_origin does not cover SSM and that dashboard_origins is the only ceiling.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved by Crew Captain for the on-call, with a maintainer design sign-off for the linked issue. Review lanes clean on this head.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Shared Crew over AWS SSM: invite-only link with the same parts as Tailscale

4 participants