@s-gw/s-gw 0.1.0

package/docs/keychain.md

@@ -0,0 +1,39 @@
+# OS Credential Store Backend
+
+s-gw can store credential values in the local OS credential store: macOS Keychain on macOS and Windows Credential Manager on Windows preview builds. Agents still receive only handles such as `s-gw:api-token:...`; the raw value is read from the local store only after s-gw has an approved local request to execute.
+
+## Add A Credential-Store-Backed Handle
+
+```bash
+printf '%s' "$MY_API_TOKEN" | s-gw secret add-keychain \
+  --name prod-api-token \
+  --type api-token \
+  --value-stdin \
+  --inject-env API_TOKEN \
+  --allow-command "$(command -v node)"
+```
+
+The raw credential is written through the bundled helper on stdin. The encrypted s-gw ledger keeps only handle metadata and an encrypted credential-store pointer:
+
+```json
+{
+  "service": "com.s-gw.sgw.secret",
+  "account": "s-gw:api-token:..."
+}
+```
+
+Use `--service SERVICE` or `SGW_SECRET_KEYCHAIN_SERVICE` when you want a separate credential-store namespace for testing, work, or isolated profiles.
+
+Automatic capture paths, including guard mode and the local console API, prefer the OS credential store on macOS and Windows. Set `SGW_SECRET_BACKEND=local` only for compatibility testing or environments without the native helper.
+
+## Local Execution Flow
+
+1. An agent sees a tokenized handle, not the credential.
+2. The agent asks s-gw to use the handle for a concrete action.
+3. s-gw applies policy and asks for approval when required.
+4. During approved execution, s-gw reads the credential from the local store and injects it into the local child process.
+5. Command output is sanitized back to handles before it is returned.
+
+## 1Password Migration Later
+
+Do not read or migrate real 1Password values as part of normal setup. The safe migration path should be an explicit user-approved command that reads selected `op://...` references, writes those values into credential-store-backed handles, updates the encrypted ledger pointers, and leaves an audit event for each migrated handle.

package/docs/onepassword.md

@@ -0,0 +1,84 @@
+# 1Password Integration
+
+s-gw can use 1Password as an optional local secret backend or migration source. The s-gw ledger stores an encrypted `op://...` reference, not the raw secret value. After the user grants reusable approval, the first approved execution reads the value from the local 1Password CLI, stores an encrypted copy in the s-gw keystore for the approval TTL, and injects that value only into approved local child processes.
+
+Agents still see typed handles such as `s-gw:api-token:...`; they never receive the raw value. One-time approvals read 1Password for that single execution. Timed, login-session, and unlimited approvals reuse the encrypted s-gw keystore copy until the approval expires or is revoked.
+
+## Requirements
+
+- Install and configure the 1Password CLI as `op`.
+- Use a 1Password secret reference:
+
+```text
+op://vault-name/item-name/[section-name/]field-name
+```
+
+The 1Password CLI also supports service-account use through `OP_SERVICE_ACCOUNT_TOKEN`; that is useful for team automation, while desktop users can rely on the normal 1Password app approval flow.
+
+## Add A 1Password-Backed Handle
+
+```bash
+s-gw onepassword status
+
+s-gw secret add-1password \
+  --name openai-prod \
+  --type api-token \
+  --ref 'op://Example/OpenAI/credential' \
+  --inject-env OPENAI_API_KEY \
+  --allow-command "$(command -v node)"
+```
+
+Use `--verify` when you want s-gw to call `op read` immediately and fail early if the reference is wrong or 1Password is locked:
+
+```bash
+s-gw secret add-1password \
+  --name openai-prod \
+  --type api-token \
+  --ref 'op://Example/OpenAI/credential' \
+  --inject-env OPENAI_API_KEY \
+  --allow-command "$(command -v node)" \
+  --verify
+```
+
+Without `--verify`, s-gw stores the encrypted reference and resolves it later, when the approved command actually runs.
+
+## Capture Text Into 1Password
+
+When a local agent or UI hands s-gw text that contains a credential, capture it through stdin so the value never appears in shell history:
+
+```bash
+s-gw onepassword capture \
+  --vault Dev \
+  --name "captured ssh credential" \
+  --text-stdin \
+  --inject-env SGW_SSH_PASSWORD \
+  --allow-command "$(command -v ssh)"
+```
+
+The command scans the supplied text, creates a 1Password item in the `Dev` vault for each detected secret, stores only an encrypted `op://...` reference in the s-gw ledger, and returns tokenized text containing `<<SGW_SECRET:...>>` handles.
+
+## Approved Execution
+
+```bash
+HANDLE="s-gw:api-token:..."
+
+s-gw request env-command "$HANDLE" \
+  --command "$(command -v node)" \
+  --inject-env OPENAI_API_KEY \
+  --arg -e \
+  --arg 'console.log(process.env.OPENAI_API_KEY)'
+
+s-gw approve req_...
+s-gw execute req_...
+```
+
+If the child process prints the secret, s-gw sanitizes it back to the handle token before returning output to the agent.
+
+## Operational Notes
+
+- The `op://...` reference is encrypted in the local s-gw store.
+- For reusable approvals, the raw value is read from 1Password once, then cached encrypted in the s-gw keystore until the approval TTL, login session, unlimited grant, revoke, clear, or credential deletion ends it.
+- For one-time approvals, s-gw does not keep a cached value after the execution.
+- `SGW_OP_CLI=/path/to/op` can point s-gw at a non-default CLI path.
+- `SGW_ONEPASSWORD_TIMEOUT_MS=60000` can extend the approval/read timeout.
+- For service-account automation, provide `OP_SERVICE_ACCOUNT_TOKEN` to the local environment that runs the s-gw daemon or CLI.

package/docs/quickstart.md

@@ -0,0 +1,104 @@
+# Quick Start
+
+This guide builds s-gw from source and exercises its approval boundary with disposable data. It does not require a real credential.
+
+Building from source requires Node.js 20 or newer and the Rust toolchain pinned by `rust-toolchain.toml`.
+
+## Build
+
+```bash
+git clone https://github.com/sgateway/s-gw.git
+cd s-gw
+npm ci
+npm run build
+npm link
+```
+
+For normal use, run `s-gw setup`. The demonstration below instead uses a temporary home and an environment-provided passphrase so it leaves the operating system credential store untouched.
+
+## Run The Trust Loop
+
+Create a disposable store:
+
+```bash
+export SGW_HOME="$(mktemp -d)/home"
+PASS="$(openssl rand -base64 32)"
+printf -v SGW_MASTER_PASSPHRASE '%s' "$PASS"
+export SGW_MASTER_PASSPHRASE
+s-gw init
+```
+
+Enroll a fake value and permit only the local `printenv` executable to receive it:
+
+```bash
+printf '%s' "demo-token-value" | s-gw secret add \
+  --name demo-token \
+  --type api-token \
+  --value-stdin \
+  --inject-env DEMO_TOKEN \
+  --allow-command "$(command -v printenv)"
+```
+
+Get the generated handle. The list contains metadata, not the credential value:
+
+```bash
+HANDLE=$(s-gw secret list | node -e '
+let data = "";
+process.stdin.on("data", chunk => data += chunk);
+process.stdin.on("end", () => console.log(JSON.parse(data)[0].handle));
+')
+```
+
+Create a request as an agent would:
+
+```bash
+REQUEST=$(s-gw request env-command "$HANDLE" \
+  --command "$(command -v printenv)" \
+  --arg DEMO_TOKEN \
+  --inject-env DEMO_TOKEN \
+  --reason "Read the disposable token")
+
+REQUEST_ID=$(printf '%s' "$REQUEST" | node -e '
+let data = "";
+process.stdin.on("data", chunk => data += chunk);
+process.stdin.on("end", () => console.log(JSON.parse(data).id));
+')
+```
+
+Execution is refused while the request is pending:
+
+```bash
+s-gw execute "$REQUEST_ID"
+```
+
+Approve it locally, then execute it:
+
+```bash
+s-gw approve "$REQUEST_ID"
+s-gw execute "$REQUEST_ID"
+```
+
+The child process reads `demo-token-value`, but the returned output contains an s-gw handle:
+
+```json
+{
+  "exitCode": 0,
+  "stdout": "<<SGW_SECRET:s-gw:api-token:...>>\n",
+  "proof": "s-gw-proof:req_...",
+  "sanitized": true
+}
+```
+
+Remove the disposable store:
+
+```bash
+rm -rf "$SGW_HOME"
+unset SGW_HOME SGW_MASTER_PASSPHRASE HANDLE REQUEST REQUEST_ID
+```
+
+## Next Steps
+
+- Run `s-gw setup` for a persistent local installation.
+- Use `s-gw agent mcp-snippet <agent>` to configure a supported client.
+- Read the [threat model](threat-model.md) before enrolling sensitive credentials.
+- Open the native app with `s-gw app open` or the fallback console with `s-gw console`.

package/docs/threat-model.md

@@ -0,0 +1,100 @@
+# Threat Model
+
+## Purpose
+
+s-gw reduces the chance that raw credentials are exposed to coding agents, model context, chat transcripts, tool results, or routine shell arguments. It keeps credential redemption and approval on the user's machine.
+
+This document describes the intended security boundary for the current preview. It is not a claim of formal verification or independent audit.
+
+## Protected Assets
+
+- raw credential values and local unlock material;
+- credential-store pointers and encrypted ledger contents;
+- approval decisions and reusable-grant scope;
+- command, environment, working-directory, and SSH destination policy;
+- sanitized execution output and audit records.
+
+## Trust Boundaries
+
+```mermaid
+flowchart TB
+    subgraph Untrusted["Agent-controlled or externally influenced"]
+      A["Agent request"]
+      O["Command output"]
+      F["Scanned text and files"]
+    end
+
+    subgraph Local["Trusted local s-gw boundary"]
+      V["Manifest and policy validation"]
+      P["User approval"]
+      S["Encrypted store"]
+      B["Credential resolver and approval broker"]
+      R["Rust execution core"]
+      Z["Bounded output sanitizer"]
+    end
+
+    A --> V
+    F --> V
+    V --> P
+    P --> B
+    S --> B
+    B --> R
+    R --> O
+    O --> Z
+    Z --> A
+```
+
+The local operating system account, s-gw broker and Rust core processes, operating system credential store, approved executable, and user approval decision are trusted for an approved action. Agent input, scanned content, command arguments, destinations, and command output are treated as untrusted.
+
+## Intended Guarantees
+
+- Agent-facing interfaces use typed handles and metadata rather than raw values.
+- A secret-backed action must match the handle's allowed command or owned SSH policy.
+- Pending actions do not execute until a policy or local user decision approves them.
+- Reusable approvals are bounded by stored request attributes and expiry or login session.
+- Credential and unlock values entered through supported commands use stdin instead of process arguments.
+- The loopback console requires a per-session token for state-changing operations.
+- Known raw credential values are replaced in captured command output before it is returned to the caller.
+- Approved environment commands run with a cleared child environment and only the allowlisted system variables plus approved credential bindings.
+- The broker verifies that the Rust result contains no known raw credential and that its proof matches the request and sanitized output.
+- Approval, execution, denial, failure, and policy activity is recorded locally.
+
+## Attacker Capabilities Considered
+
+- A coding agent may create arbitrary tool requests and misleading reasons.
+- Repository content may contain prompt injection or request unsafe commands.
+- A local web page may attempt to call the loopback console.
+- A child process may print the injected credential in its output.
+- An attacker may guess handles, request IDs, or local API routes.
+- A request may be interrupted by process exit, sleep, or a hung command.
+
+## Non-Goals And Residual Risk
+
+s-gw does not protect against:
+
+- compromise of the current operating system account, kernel, credential store, or s-gw process;
+- a malicious or compromised executable that the user approves to receive a credential;
+- screen capture, keylogging, debugger access, process-memory inspection, or privileged endpoint monitoring;
+- network exfiltration performed by an approved command;
+- every transformed, encoded, hashed, fragmented, or derived representation of a credential in output;
+- secrets the user pastes directly into chat, source files, terminal commands, or agent configuration;
+- credential access by tools that bypass s-gw entirely;
+- broad prompt, file, terminal, or operating system interception solely through MCP registration;
+- denial of service, destructive approved commands, or incorrect user approval decisions.
+
+Output sanitization is a last line of defense, not a data-loss-prevention guarantee. Keep allowed commands narrow, review destinations and arguments, and use low-privilege credentials with independent provider-side controls.
+
+## Secure Use
+
+- Enroll credentials from a local terminal or supported UI, never from agent chat.
+- Prefer macOS Keychain or Windows Credential Manager over environment-provided unlock material.
+- Use absolute executable paths for command grants where practical.
+- Keep reusable approvals short and scoped to one agent when possible.
+- Treat unlimited approvals and high-severity credentials as exceptional.
+- Review SSH destinations, ports, and remote commands before approval.
+- Keep the operating system, Node.js, s-gw, and credential providers updated.
+- Review the local audit log and revoke stale policies and grants.
+
+## Reporting
+
+Report suspected boundary failures through the private process in [SECURITY.md](../SECURITY.md). Do not test with credentials or systems you do not own or have permission to use.

package/docs/ui/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,111 @@
+# Third-Party Notices
+
+## Rust Execution Core
+
+The compiled `sgw-core` runner uses crates from crates.io. Exact versions are
+locked in `Cargo.lock`.
+
+- `base64`, `block-buffer`, `cfg-if`, `cpufeatures`, `crypto-common`, `digest`,
+  `itoa`, `libc`, `proc-macro2`, `quote`, `serde`, `serde_core`, `serde_derive`,
+  `serde_json`, `sha2`, `syn`, `typenum`, and `version_check`: MIT or Apache-2.0
+- `generic-array` and `zmij`: MIT
+- `memchr`: Unlicense or MIT
+- `unicode-ident`: MIT or Apache-2.0, with Unicode-3.0 data terms
+
+Sources and license files are available through each package entry at
+https://crates.io/ and in the corresponding Cargo registry source archive.
+
+## AWS Architecture Icons
+
+The macOS approval helper includes the Amazon EC2 service icon from the official
+AWS Architecture Icons package. This asset is used only to identify Amazon EC2.
+AWS and Amazon EC2 are trademarks of Amazon.com, Inc. or its affiliates.
+
+- Source: https://aws.amazon.com/architecture/icons/
+
+## Lucide Icons
+
+The local console and native macOS menu helper embed selected Lucide SVG icons.
+The helper uses Lucide for generic agent, terminal, server, and local-machine
+concepts while retaining service-specific marks where identity matters.
+
+- Source: https://lucide.dev/
+- Package: `lucide-react@1.23.0`
+- License: ISC
+
+The selected icons are embedded directly in `local-console.html` so the local credential console works offline and does not call a CDN.
+
+## Simple Icons
+
+The credential provider table embeds the GitHub SVG mark from Simple Icons 16.22.0.
+
+- Source: https://simpleicons.org/
+- Package: `simple-icons@16.22.0`
+- License: CC0-1.0
+
+Simple Icons supplies brand SVGs; trademark rights remain with the respective brand owners. AWS and OpenAI remain text marks in the legacy prototype because the package used there did not include matching current SVG marks under those provider names.
+
+The React console also uses the Claude, Google Gemini, GitHub Copilot, and
+Windsurf marks from Simple Icons 16.22.0 to identify known coding agents.
+
+The React Credentials view uses the 1Password mark from Simple Icons 16.24.1
+to make the provider immediately recognizable. The mark is bundled locally;
+1Password remains a trademark of AgileBits, Inc.
+
+## Installed Application Icons
+
+The React console includes scaled application icons for Codex, Cursor, OpenCode,
+and Visual Studio Code so approval and activity views use the product artwork
+users already recognize. These icons are used only for product identification.
+The products and their artwork remain trademarks of their respective owners and
+are not licensed under s-gw's Apache-2.0 license.
+
+- Codex: https://openai.com/codex/
+- Cursor: https://cursor.com/
+- OpenCode: https://github.com/anomalyco/opencode
+- Visual Studio Code: https://github.com/microsoft/vscode
+
+## Agent Project Artwork
+
+The React console uses artwork from the following official project repositories
+to identify configured agents. The artwork is used only for product
+identification; project names and marks remain with their respective owners.
+
+- OpenClaw: https://github.com/openclaw/openclaw (MIT)
+- ZeptoClaw: https://github.com/qhkm/zeptoclaw (Apache-2.0)
+- Hermes Agent: https://github.com/NousResearch/hermes-agent (MIT)
+- OpenHands: https://github.com/OpenHands/OpenHands (MIT outside `enterprise/`)
+- OmniGent: https://github.com/omnigent-ai/omnigent (Apache-2.0)
+
+The Google Antigravity favicon is sourced from the official Antigravity site and
+is used only to identify that product. Google and Antigravity are trademarks of
+Google LLC.
+
+- Source: https://www.antigravity.google/
+
+## d3-sankey and d3 Modules
+
+The Usage Flow panel uses d3-sankey for the local, offline Agent -> Credential -> Action Sankey chart. The browser bundles are vendored so the console does not call a CDN.
+
+- Source: https://github.com/d3/d3-sankey
+- Package: `d3-sankey@0.12.3`
+- File: `docs/ui/vendor/d3-sankey/d3-sankey.min.js`
+- License: BSD-3-Clause
+
+d3-sankey's browser bundle depends on these d3 modules, also vendored locally:
+
+- `d3-array@2.12.1`, BSD-3-Clause, `docs/ui/vendor/d3-sankey/d3-array.min.js`
+- `d3-path@1.0.9`, BSD-3-Clause, `docs/ui/vendor/d3-sankey/d3-path.min.js`
+- `d3-shape@1.3.7`, BSD-3-Clause, `docs/ui/vendor/d3-sankey/d3-shape.min.js`
+
+The upstream BSD license files are included beside the bundles in `docs/ui/vendor/d3-sankey/`.
+
+## SankeyMATIC
+
+A legacy SankeyMATIC layout-core copy remains in the repository from an earlier prototype but is not loaded by the current Usage Flow panel.
+
+- Source: https://github.com/nowthis/sankeymatic
+- File: `docs/ui/vendor/sankeymatic/sankey.js`
+- License: ISC
+
+The upstream ISC license is included at `docs/ui/vendor/sankeymatic/LICENSE.txt`.