Support Session Management Architecture
Status: Draft for Review System: Angular + Spring Boot 4.0.5 (Java 25) + Auth0 Date: October 2026 Driver: Sky Ledge support engineers must be able to act inside a customer organization to diagnose and fix problems, without sharing customer credentials and without ever obtaining the organization’s API keys Author: Nimash
Table of Contents
- Problem & Design
- System Actors
- Session Lifecycle
- API
- Support Session Cookie & Request Origin Check
- Who May Open and Use a Session
- Offboarding
- Permission Scope
- Audit Trail
- Security Controls & Attack Scenarios
- Known Gaps & Production Readiness
1. Problem & Design
Every user belongs to exactly one organization, and the invitation signup flow guarantees that only an organization can add members to itself. Support engineers belong to the Sky Ledge support organization, so by construction they can’t see or touch a customer’s data. Support work still needs that access occasionally, and it must be granted in a way that is narrower, shorter-lived and more visible than membership.
Core principle: a support session is a time-boxed, reasoned, audited grant for one engineer to act in one target organization. The engineer never gets a new identity. They stay logged in with their own BFF session (the SESSION cookie, relayed to their own Auth0 JWT), and a second cookie, SUPPORT_SESSION, names the support session they are currently working in. While that cookie is present and the session is valid, the API server resolves the request as the target organization’s owner.
This builds on the cookie-based BFF login documented in cookie-based-authentication-implemantation/architecture.md; JWT validation and SESSION → bearer relay are not re-derived here.
| Property | Description |
|---|---|
| Grant, not membership | The session itself never makes the engineer a member of the target organization. A READ_WRITE session can still make changes that outlive it, such as an invite or a registered device (accepted risk, §8). |
| Time-boxed | Every session has an expiresAt between 1 and 120 minutes (2 hours) after creation. Expiry is checked on every request, and an expired session can’t be extended: an officer who needs longer creates a new session, with a new reason. |
| Reasoned | A non-blank reason is mandatory on creation and stored with the session. |
| Scoped | READ_ONLY or READ_WRITE. /api-key is blocked in every session regardless of scope. |
| Revocable | The officer who opened a session, or the support organization owner, can revoke it. Revocation, logout, exit and deactivating the engineer all end access. Revocation is effective on the very next request because the session is re-read from the database every time. |
| Audited | Every write made in a session, successful or not, is sent to the support-audit-log-queue SQS FIFO queue with method, path, status, IP, duration and body. Refused reads and refused session attempts are sent too, without a body. Other reads are not audited. |
| Cookie-carried | The session id travels in an HttpOnly cookie set by the server, so page scripts can’t read or forge it. |
2. System Actors
| Actor | Role | Trust |
|---|---|---|
| Angular SPA | Creates a session, enters it (server sets the cookie), shows support mode via GET /support/sessions/current, exits or revokes. Never sees the session id in a header. |
Partial |
| Browser | Carries SESSION (BFF login) and SUPPORT_SESSION (current support session) on every same-site request, and sends the Sec-Fetch-* and Origin headers used by the request origin check. |
Untrusted |
Spring Boot — apiServerChain (@Order(3)) |
Filter order is load-bearing: ApiKeyFilter → SessionTokenRelayFilter → BearerTokenAuthenticationFilter → SupportSessionFilter → SupportPermissionScopeFilter. Support handling runs only after the engineer’s own JWT is validated. |
Fully trusted |
SupportSessionAwareAuthProvider (@Primary AuthProvider) |
If the request carries an active session, resolves userIdFromPrincipal to the target organization’s owner and organizationIdFromPrincipal to the target organization. Otherwise delegates to AuthProviderAuth0Adapter. |
Fully trusted |
Spring Boot — bffLoginChain |
/bff/logout deletes SUPPORT_SESSION together with SESSION and JSESSIONID. |
Fully trusted |
PostgreSQL support_session |
One row per session: engineer id and email, target organization, reason, scope, created_at, expires_at, revoked_at, revoked_by, last_activity_at. Never deleted. |
Trusted |
SQS FIFO support-audit-log-queue |
One message per mutating request made in a session, whatever its outcome (§9). The application never reads it back. | Trusted |
3. Session Lifecycle
There are two independent states: whether the session is still valid, and whether the engineer’s browser is currently in support mode (holds the cookie).
Session: [created] ──▶ ACTIVE ──(expires_at passes)──────────────────▶ EXPIRED │ └──(DELETE /support/sessions/{id}, or engineer deactivated)──▶ REVOKED
Browser: normal ──(POST /{id}/enter: Set-Cookie SUPPORT_SESSION)──▶ support mode support mode ──(POST /exit | revoke of current | /bff/logout | any dead-session refusal)──▶ normal| Transition | Set by |
|---|---|
| Created | SupportSessionCreator.create(): checks the engineer is active and has fewer than support.max-concurrent-sessions (env SUPPORT_MAX_CONCURRENT_SESSIONS, default 5 when unset) active sessions, then saves with expiresAt = now + durationMinutes. At the limit it is refused with 409. Creating does not enter the session. |
| Entered | EnterSupportSessionController: loads the session only if it is active and owned by the caller, then writes the cookie with max-age equal to the session’s remaining lifetime. |
| Activity | SupportSessionFilter → SupportSessionLookup.recordActivityOn() sets last_activity_at with a single UPDATE of that column only, and only if it is empty or more than a minute old. It never writes the rest of the row, so it can’t undo a revocation that happens while the request is running, and a burst of requests writes at most once a minute. |
| Exited | ExitSupportSessionController: clears the cookie. The session stays active and can be entered again until it expires. |
| Revoked | SupportSessionRevoker sets revoked_at/revoked_by. Only the officer who owns the session or the support organization owner may revoke it; anyone else gets 403. Revoking a session that has already expired or been revoked is refused with 409. If the revoked session is the one in the caller’s cookie, the cookie is cleared in the same response. |
| Expired | Implicit: isActive() is !revoked && expiresAt > now. No job; checked on read. At most 2 hours after creation. Expired sessions can’t be renewed or extended; the officer creates a new one. |
The cookie never outlives the session by design (max-age = remaining lifetime), and if it does survive (clock drift, revocation from another tab), the first request with a dead session clears it.
4. API
All endpoints live under /support/sessions. SupportSessionFilter lets these requests through without activating the session even when the cookie is present, so they always see the real engineer, never the target organization’s owner.
Callers
| Caller | Who that is |
|---|---|
| Support officer | Any user whose organization is the support organization (support.skyledge-organization-id), including its owner. |
| Support organization owner | The owner of the support organization. An officer with extra rights over other officers’ sessions. |
| Customer user | Any logged-in user outside the support organization, including a target organization’s owner and its members. |
| Unauthenticated | No valid SESSION cookie or bearer token. apiServerChain requires authentication on every /support/sessions/** endpoint, so these always get 401. |
| API key | A request authenticated with an organization’s API key. SupportSessionFilter refuses every /support/sessions/** request with 403 before it reaches a controller, whichever organization the key belongs to (§6). |
Access is enforced by @PreAuthorize on SupportSessionCreator, SupportSessionRetriever and SupportSessionRevoker, decided by SupportSessionPermissionChecker. exit and the no-cookie path of current have no permission check beyond being logged in.
Endpoints
| Method & path | Purpose | Who can call | Who is refused | Notes |
|---|---|---|---|---|
POST /support/sessions |
Create a session | Support officer, for themselves only | Customer user: 403. Also 403 if the target organization doesn’t exist, is the caller’s own organization, or the caller is deactivated. 409 at the concurrent-session limit. | Body: targetOrganizationId, reason, permissionScope (READ_ONLY / READ_WRITE), durationMinutes (1–120, i.e. at most 2 hours); invalid body 400. Returns 201. |
POST /support/sessions/{id}/enter |
Enter support mode | Support officer, only into their own active session | Customer user: 403. Officer whose session id is unknown, expired, revoked or belongs to another officer: 404. The support organization owner can’t enter another officer’s session either (404). | Sets SUPPORT_SESSION. |
POST /support/sessions/exit |
Leave support mode | Any authenticated user, support officer or customer user | Only unauthenticated (401) and API key (403). | Clears the cookie. Returns 204. Does not revoke. |
GET /support/sessions/current |
What the SPA should show | Support officer. Any authenticated user may call it, but only an officer ever gets a session back. | Only unauthenticated (401) and API key (403). | 200 with the session if the cookie names an active session owned by the caller. 410 Gone with the ended session (its expiresAt and revokedAt say which) if that session has expired or been revoked; the cookie is cleared. 204 if there is no cookie. Also 204, with the cookie cleared, if the cookie is malformed, names no session, names another officer’s session, or the caller is a customer user, so nothing about other sessions is revealed. |
GET /support/sessions |
List the caller’s own active sessions | Support officer (always their own; there is no parameter to ask for someone else’s) | Customer user: 403. | |
GET /support/sessions/active |
List every officer’s active sessions | Support organization owner only | Other support officers and customer users: 403. | Optional targetOrganizationId narrows it to the sessions currently open into one organization, i.e. who is inside a customer organization right now. A malformed id returns 400. |
GET /support/sessions/{id} |
Get one session | The officer who owns it, or the support organization owner (any session) | Another officer, or a customer user: 403. An officer asking for an unknown id also gets 403; the support organization owner gets 404. | |
DELETE /support/sessions/{id} |
Revoke | The officer who owns it, or the support organization owner (any officer’s session) | Another officer, or a customer user: 403 (also for an unknown id, except the support organization owner gets 404). 409 if the session has already expired or been revoked. | Clears the cookie if it names this session. |
Endpoint × caller summary
| Endpoint | Support officer | Support organization owner | Any other organization user/owner (incl. target organization owner) | Unauthenticated | API key |
|---|---|---|---|---|---|
POST /support/sessions |
✅ for self | ✅ for self | ❌ 403 | ❌ 401 | ❌ 403 |
POST /support/sessions/{id}/enter |
✅ own active only | ✅ own active only | ❌ 403 | ❌ 401 | ❌ 403 |
POST /support/sessions/exit |
✅ | ✅ | ✅ | ❌ 401 | ❌ 403 |
GET /support/sessions/current |
✅ | ✅ | ✅ always 204 | ❌ 401 | ❌ 403 |
GET /support/sessions |
✅ own | ✅ own | ❌ 403 | ❌ 401 | ❌ 403 |
GET /support/sessions/active |
❌ 403 | ✅ all | ❌ 403 | ❌ 401 | ❌ 403 |
GET /support/sessions/{id} |
✅ own only | ✅ any | ❌ 403 | ❌ 401 | ❌ 403 |
DELETE /support/sessions/{id} |
✅ own only | ✅ any | ❌ 403 | ❌ 401 | ❌ 403 |
The target organization’s owner has no say over sessions opened into their organization: they can’t list, view, revoke or be notified of them (consent and notification are planned for v2, §11).
5. Support Session Cookie & Request Origin Check
Cookie (SupportSessionCookie):
| Attribute | Value | Why |
|---|---|---|
| Name | SUPPORT_SESSION |
|
| Value | The session UUID | It is only a pointer. It grants nothing on its own; the server re-checks ownership and validity every request. |
HttpOnly |
true | Page scripts (including an XSS payload) can’t read or set it. |
Secure |
server.servlet.session.cookie.secure (default true) |
Same setting as the BFF SESSION cookie. |
SameSite |
Lax |
Not sent on cross-site sub-requests (fetch/XHR/forms with POST). |
Path |
/ |
|
Max-Age |
Remaining session lifetime; 0 to clear |
Request origin check. CSRF protection is disabled on apiServerChain, and SameSite=Lax still sends the cookie on top-level cross-site GET navigations. So SupportSessionFilter only accepts a support session request when it can tell the request came from the app itself:
Sec-Fetch-Mode: navigate→ refused. A support session is never activated by a page load or a link click, only by the SPA’s own API calls.Sec-Fetch-Site: same-origin→ accepted.- Otherwise,
Originmust be one ofincontrol.api-client.cors-allowed-origins→ accepted; anything else → refused with 403.
A request without the cookie skips all of this and is handled normally, and so do /support/sessions/** and /bff/password-change even with the cookie, because they always act as the engineer (§6). The one exception is an API-key request to /support/sessions/**, which is refused with or without the cookie (§6).
6. Who May Open and Use a Session
Creating (SupportSessionPermissionChecker, via @PreAuthorize on SupportSessionCreator):
- The caller’s organization is
support.skyledge-organization-id, set through theSUPPORT_SKYLEDGE_ORGANIZATION_IDenvironment variable (application.yamldefaults it toto_be_provided). If the value is not a UUID, every support session permission check fails with anIllegalStateException(500) whose message names the missing variable, so the misconfiguration shows up in the logs instead of as a silent 403. - The command’s
supportUserIdis the caller. An engineer can’t open a session for someone else. - The target organization exists.
- The target organization is not the caller’s own organization.
- The caller’s user record is active (checked in
SupportSessionCreator). - The caller has fewer than
support.max-concurrent-sessionsactive sessions (default 5 when theSUPPORT_MAX_CONCURRENT_SESSIONSenvironment variable is not set).
Viewing and revoking:
| Caller | List own sessions | List every officer’s sessions (/active) |
View or revoke a session |
|---|---|---|---|
| Officer (support organization member) | Yes | No | Only their own |
| Support organization owner | Yes | Yes | Any officer’s |
| Anyone else | No | No | No |
“Support organization owner” is the owner of the organization configured as support.skyledge-organization-id.
Using a session. An engineer in support mode acts as the customer organization’s owner, but only when every one of these holds for the request:
- It comes from a person, not an integration. Requests made with an organization’s API key never act inside a support session. An API key is a machine credential of one organization; letting it ride a session would let a key from the support organization act in any customer organization.
- It isn’t managing sessions or changing the engineer’s own password. Creating, entering, exiting, listing and revoking sessions, and
/bff/password-change, always act as the engineer themselves, never as the customer’s owner. The password change is a page load, which rule 4 would otherwise refuse, so an engineer in support mode can still change their own password. - The engineer is logged in. Without a valid login the support session is simply ignored; the request is treated like any other unauthenticated request.
- It comes from the Sky Ledge app. Not from a link, a page load or another website (§5).
- The session exists and belongs to this engineer. An engineer can never use a colleague’s session, even with its id.
- The session is still active. It hasn’t expired or been revoked.
If check 1, 4, 5 or 6 fails, the request is refused and the attempt is recorded in the audit trail (§9). When the session is missing, belongs to someone else or has ended (5 and 6), the engineer is also dropped back to normal mode. A request refused for coming from outside the app (4) leaves support mode untouched, so a malicious link can’t end it. Once every check passes, the request acts as the customer organization’s owner, limited by the session’s scope (§8).
7. Offboarding
Deactivating a user blocks them in Auth0, but the access token they already hold stays valid until it expires. Without offboarding, a deactivated engineer could keep using open support sessions, or open new ones into any customer organization, during that window.
UserUpdater (deactivate) └─ publishes UserDeactivatedEvent(userId, deactivatedBy) └─ UserDeactivatedEventHandler.revokeActiveSupportSessions() (synchronous @EventListener) └─ revoke every active session of userId with revoked_by = deactivating adminThe listener is synchronous: it runs on the deactivating request’s thread, so every active session is already revoked when the deactivation call returns, with no window in which an open session still works. Creating a session additionally requires the engineer to be active, so a new session can’t be opened either. Because SupportSessionFilter re-reads the session on every request, the revocation takes effect on the next request and clears the cookie.
8. Permission Scope
SupportPermissionScopeFilter runs only when a session is attached to the request. Paths are URL-decoded before matching.
The filter applies three rules in order:
/api-key(/…)is blocked in every session, for every method and regardless of scope (403This endpoint is not available during a support session.).READ_ONLYsessions reject any method other thanGET,HEADandOPTIONS, exceptPOST …/search, which is a read (403Support session is read-only…).READ_WRITEsessions may call every other endpoint.
Why /api-key is the only blocked path
While a session is active, SupportSessionAwareAuthProvider resolves the caller as the target organization’s owner, so every request runs with the owner’s full authority inside an organization the engineer does not belong to. Sky Ledge accepts that a READ_WRITE session can do anything the owner can, with one exception:
| Path | Methods | What the endpoint does | Why it stays blocked |
|---|---|---|---|
/api-key(/…) |
All, including reads | GET /api-key returns the organization’s live API key values and creates any missing key types on the fly (ApiKeyRetriever). |
Credential exfiltration. One read would hand the engineer a long-lived organization credential that works from anywhere, with no session, scope, audit or expiry. API-key requests can never carry a support session (§6), so anything done with the key bypasses this design entirely. Because the “read” also mints keys, it is a write in disguise, so blocking writes only would not be enough. |
The path is matched after URL decoding, so encoded variants such as /%61pi-key can’t slip past. A blocked write is sent to the audit queue with status 403, and a blocked GET /api-key is sent as a lightweight refused-request event without a body (§9).
Accepted risks
Every other endpoint is open in a READ_WRITE session. These are the risks that come with it, accepted on the basis that support engineers are trusted Sky Ledge staff and that every write is audited (§9):
| Path | What a support engineer can now do | Accepted risk |
|---|---|---|
/users/invite(/…) |
Invite people into the customer’s organization through the invitation signup flow. | Self-invite escalation. The engineer could invite their own email, or one they control. Redeeming it creates a real member account that is not time-boxed, not scope-limited and not removed by revocation, expiry or deactivating the engineer, so temporary support access can become standing access to the customer’s organization. |
/controlrooms/{id}/invite(/…) |
Assign collaborators to a control room; invitees without an account are invited into the organization (UserInviteRequestedEvent). |
The same self-invite escalation, reached through control-room collaboration. |
/users(/…) writes |
POST /users creates a user directly. PUT /users/{id} sets a user’s active flag, which also blocks or unblocks them in Auth0. |
Planting or reviving an account, such as a former employee or an account the engineer controls. Locking customers out by deactivating their users, including the owner. |
/me(/…) writes |
/me is the organization owner during a session: profile (PUT /me), push-notification devices (PUT /me/devices), notification preferences, mailing list. |
Changes in the owner’s name on their personal profile. Persistence through notifications: a device the engineer registers on the owner’s account keeps receiving the owner’s push notifications after the session ends. Preference changes can silently stop the owner receiving alerts. |
/organization(/…) writes |
PUT /organization changes the organization’s name and time zone. POST /organization creates a new organization. |
Organization-wide side effects that are hard to notice afterwards (customer-facing name, schedules and date boundaries), and creating a tenant on the owner’s behalf. |
/billing(/…) |
View plan, invoices and payment methods; POST /billing/payment-methods authorizes a payment method. |
Financial data exposure and financial commitments made in the customer’s name. |
Because of these, a session that has ended no longer guarantees that the engineer has nothing left in the organization: an invite, a created or revived user, or a registered device can outlive it. The audit trail (§9) is what makes such changes visible after the fact.
Why READ_ONLY treats POST …/search as a read
Several list endpoints take their filters in a POST body because the filter is too complex for a query string. They change nothing, so a read-only engineer needs them to see the same lists as the customer. Every other POST, PUT, PATCH and DELETE is refused in a READ_ONLY session.
9. Audit Trail
Audit events are not stored in the database. Each audited request becomes one text message on the SQS FIFO queue support-audit-log-queue (support-audit-log-queue.fifo on AWS, since FIFO queue names must end in .fifo). Storing and querying the trail is the queue consumer’s job, not the API server’s. The earlier support_audit_log table is dropped (V202610261200__drop_support_audit_log.sql); any rows it held are deleted.
What is audited. Every request that can change data: every method other than GET, HEAD and OPTIONS. That covers POST, PUT, PATCH and DELETE, and includes POST …/search, which READ_ONLY sessions treat as a read (§8). Reads are audited only when they are refused. Every attempt that SupportSessionFilter refuses is audited as well, even though no valid session is attached.
SupportSessionFilter lets reads through without capturing their body, and wraps every accepted write in a ContentCachingRequestWrapper and times it. Because the engineer acts with the organization owner’s authority, the body is what makes a support change reconstructable: the path says what was called, the body says what was changed.
| Outcome | Where it goes |
|---|---|
Write, any response (2xx, 4xx, 5xx, including 403s from SupportPermissionScopeFilter) |
A SUPPORT_REQUEST message with the request body. Writes refused by the scope filter, such as a READ_ONLY write or a write to /api-key, are on the queue alongside successful changes. If an exception escapes the request handling, the event records status 500 rather than the status the response had at that moment. |
Read refused by SupportPermissionScopeFilter (a GET /api-key) |
A lightweight REFUSED_SUPPORT_REQUEST message: the same fields without a request body. |
Any other read (GET, HEAD, OPTIONS) |
Nothing. |
Refused by SupportSessionFilter (no valid session to attach the event to) |
A REFUSED_SUPPORT_SESSION message, plus a structured WARN log line Session Management Audit: refused reason=…. The reason is one of API_KEY_NOT_ALLOWED, UNTRUSTED_REQUEST_ORIGIN, MALFORMED_SESSION_ID, SESSION_NOT_FOUND, SESSION_EXPIRED_OR_REVOKED. |
| Message fails to send | ERROR log line in the API server logs, and the request carries on; it has already been answered. |
| Revoked by deactivation | INFO log line with the count, user and revoking admin. |
Message. One message per request. Its body is a single JSON text document holding the whole event, request body included:
{ "eventId": "6f1c…", "timestamp": "2026-10-26T03:14:07.512Z", "sessionId": "2b7e…", "supportUserId": "a91d…", "supportUserEmail": "engineer@skyledge.com", "targetOrganizationId": "c40f…", "requestMethod": "PUT", "requestUri": "/controlrooms/8d2a…", "responseStatus": 200, "clientIp": "203.0.113.7", "durationMs": 42, "requestBody": "{\"name\":\"Pump 4\"}", "requestBodyTruncated": false, "eventType": "SUPPORT_REQUEST"}A REFUSED_SUPPORT_REQUEST has the same fields, with requestBody null. A REFUSED_SUPPORT_SESSION describes an attempt that never reached a session:
{ "eventId": "91aa…", "timestamp": "2026-10-26T03:15:42.004Z", "reason": "SESSION_EXPIRED_OR_REVOKED", "supportUserId": "a91d…", "requestedSessionId": "2b7e…", "requestMethod": "PUT", "requestUri": "/controlrooms/8d2a…", "responseStatus": 401, "clientIp": "203.0.113.7", "eventType": "REFUSED_SUPPORT_SESSION"}supportUserId is null when the request carries no verified engineer, and requestedSessionId is the session id exactly as sent, so it may not be a valid id.
| SQS attribute | Value | Why |
|---|---|---|
MessageGroupId |
sessionId; for REFUSED_SUPPORT_SESSION, the engineer id (or unauthenticated) |
Events of one session are delivered in the order they happened, while different sessions don’t hold each other up. |
MessageDeduplicationId |
A new random id per send, generated by Spring Cloud AWS | The queue uses explicit deduplication (ContentBasedDeduplication=false, as for every FIFO queue MessageQueueCreator creates). Two identical requests within the 5-minute deduplication window are two separate events and must both arrive, so content-based deduplication would be wrong. Consumers deduplicate on eventId. |
token, correlationId |
Added by MessageSenderSQSAdapter to every message |
On audit messages token is masked to **** plus the last 4 characters of the engineer’s access token, so the queue never holds a usable token. Other queues still get the full token, which their listeners need to act as the caller. |
The queue is the SUPPORT_AUDIT_LOG_QUEUE FIFO entry in the MessageQueue enum, so MessageQueueCreator creates it, with its dead-letter queue, at startup like rule-execution-fifo-queue. Sending goes through the existing MessageSender (MessageSenderSQSAdapter). The payload is built by SupportAuditMessageComposer from a SupportAuditEvent.
Sending is asynchronous. The filter builds the SupportAuditEvent from the request and response on the request thread, then hands the composing and sending to the application TaskExecutor, so the response doesn’t wait for SQS. The caller’s security context and logging context (correlation id) are carried over to the sending thread.
Request body recording:
| Content type | Recorded as |
|---|---|
text/*, application/json, application/xml, application/x-www-form-urlencoded, any +json / +xml type, or no content type |
The body as text in the request’s charset (UTF-8 by default). Null when empty. |
Anything else (multipart/form-data, application/octet-stream, images, …) |
A placeholder, e.g. [multipart/form-data body, 2048 bytes not recorded], so file uploads don’t fill the queue with decoded binary. The size is omitted when the request has no Content-Length. |
Bodies are sent in full unless they don’t fit in one message. SQS accepts at most 1 MiB (1,048,576 bytes) per message, attributes included. The JSON payload is capped at 983,040 bytes (SupportAuditMessage.MAX_PAYLOAD_BYTES), leaving 64 KiB for the message attributes.
- If the whole event fits, the body is sent exactly as received and
requestBodyTruncatedisfalse. - Otherwise
SupportAuditMessageComposerkeeps the longest prefix of the body that still fits, measured in UTF-8 bytes after JSON escaping and never splitting a character, and setsrequestBodyTruncatedtotrue. - The request wrapper caches at most the payload limit plus one byte, so an oversized body is never held in memory in full.
All log lines share the Session Management Audit: prefix so they can be queried together.
10. Security Controls & Attack Scenarios
Blocked endpoints and accepted risks
/api-key is the only endpoint blocked in a session, for reads as well as writes, so a session can never hand the engineer a long-lived organization credential that works outside this design (§8).
Every other owner capability is available in a READ_WRITE session, and its risks are accepted (§8):
| Accepted risk | Endpoints |
|---|---|
| Self-invite escalation: a permanent member account for the engineer in the customer’s organization | /users/invite, /controlrooms/{id}/invite, POST /users |
| Reviving a removed user, or locking customers out | PUT /users/{id} |
| Persisting through the owner’s identity (push devices, notification preferences, profile) | /me writes |
| Organization-wide side effects (name, time zone, new tenant) | /organization writes |
| Financial data and commitments | /billing |
The mitigations are that sessions are reasoned, time-boxed and revocable, engineers are trusted Sky Ledge staff, and every write in a session is on the audit queue (§9).
11. Known Gaps & Production Readiness
Open
| Gap | Impact | Plan |
|---|---|---|
| Nothing consumes the audit queue yet. | MessageQueueCreator gives queues a 4-day retention, so until the queue is consumed, audit events are lost after 4 days. |
Route the queue through Amazon Data Firehose into a secure S3 bucket, set up purely in AWS: sc-12042. |
Accepted
| Behaviour | Why it is accepted |
|---|---|
| Actions are attributed to the organization owner in the customer’s own data (created-by, updated-by, activity feeds). | The support audit trail records which officer made each change. |
READ_WRITE sessions have the owner’s full authority except /api-key. An engineer can invite themselves, create or revive users, register devices on the owner’s account, change organization settings and see or change billing. |
Accepted behaviour; every write is on the audit queue (§8). |
Only /api-key is blocked. |
/api-key is the only endpoint that returns credentials. |
| A failed send doesn’t fail the request. | The API server logs an ERROR and carries on; support work is not blocked by an SQS problem. |
| Audit events waiting to be sent can be lost when an instance stops or crashes, because they are sent after the response from a thread pool. | Accepted. |
| Request bodies are sent as received, sensitive values included. | The audit logs are stored in a secure S3 bucket. |
Bodies over the message limit are truncated (about 960 KB); requestBodyTruncated flags it. |
Accepted. |
Planned for v2
| Feature | Note |
|---|---|
| Customer consent and notification | Customers aren’t told when support enters their organization. Notifying the owner, and optionally requiring approval, is planned for v2 of the feature. |