aquaman-proxy 0.16.0 → 0.17.0

package/dist/openshell/integration.js

@@ -0,0 +1,69 @@
+/**
+ * Glue between `aquaman daemon` / the CLI and the OpenShell credential driver.
+ */
+import * as path from 'node:path';
+import { getConfigDir } from '../core/utils/config.js';
+import { createOpenShellDriverCore } from './credential-driver.js';
+import { startOpenShellDriverServer, loadGrpc } from './grpc-server.js';
+/** macOS caps Unix socket paths at 104 bytes (Linux 108); bind fails above that. */
+export const MAX_SOCKET_PATH = 103;
+export function openshellDriverSocketPath(config) {
+    return config.openshell?.driver?.socketPath || path.join(getConfigDir(), 'openshell.sock');
+}
+/** True when the optional gRPC peers can be loaded. */
+export async function grpcAvailable() {
+    try {
+        await loadGrpc();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The gateway TOML that points OpenShell at this driver. */
+export function gatewayConfigSnippet(socketPath) {
+    return [
+        '[openshell.gateway]',
+        'credential_drivers = ["aquaman"]',
+        '',
+        '[openshell.credential_drivers.aquaman]',
+        'transport = "uds"',
+        `socket_path = "${socketPath}"`,
+    ].join('\n');
+}
+/**
+ * Resolves hand a value to the gateway (`read`); copy-mode writes and deletes
+ * change the vault (`rotate`). Validating a reference at create time hands
+ * nothing out, so only its refusals are recorded.
+ */
+export function auditDriverAccess(audit, e) {
+    let operation;
+    if (e.op === 'resolve')
+        operation = 'read';
+    else if (e.mode === 'copy')
+        operation = 'rotate';
+    else if (!e.success)
+        operation = 'read';
+    else
+        return;
+    audit.logCredentialAccess('system', 'openshell', {
+        service: e.service,
+        operation,
+        success: e.success,
+        error: e.success ? undefined : `${e.ref}: ${e.error ?? 'refused'}`,
+    });
+}
+export async function startOpenShellDriver(opts) {
+    const socketPath = openshellDriverSocketPath(opts.config);
+    if (Buffer.byteLength(socketPath) > MAX_SOCKET_PATH) {
+        throw new Error(`socket path is ${Buffer.byteLength(socketPath)} bytes, over the ${MAX_SOCKET_PATH}-byte Unix socket limit: ${socketPath}. Set openshell.driver.socketPath to a shorter path.`);
+    }
+    const core = createOpenShellDriverCore({
+        store: opts.store,
+        scope: opts.scope,
+        version: opts.version,
+        onAccess: (e) => auditDriverAccess(opts.audit, e),
+    });
+    return startOpenShellDriverServer(core, socketPath);
+}
+//# sourceMappingURL=integration.js.map

package/dist/openshell/integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.js","sourceRoot":"","sources":["../../src/openshell/integration.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAIlC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAA0B,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,0BAA0B,EAAE,QAAQ,EAA8B,MAAM,kBAAkB,CAAC;AAEpG,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAEnC,MAAM,UAAU,yBAAyB,CAAC,MAAqB;IAC7D,OAAO,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,gBAAgB,CAAC,CAAC;AAC7F,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,IAAI,CAAC;QACH,MAAM,QAAQ,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,OAAO;QACL,qBAAqB;QACrB,kCAAkC;QAClC,EAAE;QACF,wCAAwC;QACxC,mBAAmB;QACnB,kBAAkB,UAAU,GAAG;KAChC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAUD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAgB,EAAE,CAAoB;IACtE,IAAI,SAA4B,CAAC;IACjC,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS;QAAE,SAAS,GAAG,MAAM,CAAC;SACtC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,SAAS,GAAG,QAAQ,CAAC;SAC5C,IAAI,CAAC,CAAC,CAAC,OAAO;QAAE,SAAS,GAAG,MAAM,CAAC;;QACnC,OAAO;IACZ,KAAK,CAAC,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE;QAC/C,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,SAAS;QACT,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,IAAI,SAAS,EAAE;KACnE,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAM1C;IACC,MAAM,UAAU,GAAG,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,eAAe,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,oBAAoB,eAAe,4BAA4B,UAAU,sDAAsD,CAAC,CAAC;IAClM,CAAC;IACD,MAAM,IAAI,GAAG,yBAAyB,CAAC;QACrC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;KAClD,CAAC,CAAC;IACH,OAAO,0BAA0B,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACtD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aquaman-proxy",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "🔱 API key protection for AI agents. Bring your own vault. Credentials stay where you already keep them, never in the agent's memory.",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,9 @@
   },
   "peerDependencies": {
     "argon2": "^0.45.1",
-    "kdbxweb": "^2.1.1"
+    "kdbxweb": "^2.1.1",
+    "@grpc/grpc-js": "^1.14.5",
+    "@grpc/proto-loader": "^0.8.1"
   },
   "peerDependenciesMeta": {
     "argon2": {
@@ -59,15 +61,22 @@
     },
     "kdbxweb": {
       "optional": true
+    },
+    "@grpc/grpc-js": {
+      "optional": true
+    },
+    "@grpc/proto-loader": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^20.19.43",
-    "tsx": "^4.23.13",
+    "tsx": "^4.23.15",
     "typescript": "^5.3.0"
   },
   "files": [
     "dist",
+    "proto",
     "LICENSE",
     "README.md"
   ],

package/proto/openshell/README.md

@@ -0,0 +1,9 @@
+# OpenShell protocol files
+
+Vendored unchanged from [NVIDIA/OpenShell](https://github.com/NVIDIA/OpenShell) at tag `v0.1.4`
+(commit `5a7728c304b5528e954e9ae900cf21f84e1a12b1`), `proto/`. Apache-2.0, see the SPDX headers in
+each file.
+
+`aquaman daemon` loads them at runtime to serve the OpenShell external credential driver
+(`credential_driver.proto`, extension protocol 1.0). Update them together with the CI lane's
+OpenShell versions.

package/proto/openshell/credential_driver.proto

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package openshell.credentials.v1;
+
+import "datamodel.proto";
+import "google/protobuf/timestamp.proto";
+import "extension.proto";
+
+// Internal credential-driver contract used by the gateway.
+//
+// The gateway owns provider semantics and sandbox delivery. Credential drivers
+// own backend-specific storage, deletion, authentication, and lookup for
+// gateway-managed provider-secret handles. Secrets include injectable provider
+// credentials and gateway-only refresh material.
+service CredentialDriver {
+  // Report driver identity and feature support.
+  rpc GetCapabilities(GetCredentialDriverCapabilitiesRequest)
+      returns (GetCredentialDriverCapabilitiesResponse);
+
+  // Store or overwrite one gateway-managed provider secret and return an opaque handle.
+  rpc StoreCredential(StoreCredentialRequest) returns (StoreCredentialResponse);
+
+  // Delete one provider credential handle.
+  rpc DeleteCredential(DeleteCredentialRequest) returns (DeleteCredentialResponse);
+
+  // Resolve a batch of credential handles into string secret values.
+  rpc ResolveCredentials(ResolveCredentialsRequest)
+      returns (ResolveCredentialsResponse);
+
+  // Optionally list discoverable credentials. Drivers may return UNIMPLEMENTED.
+  rpc ListCredentials(ListCredentialsRequest) returns (ListCredentialsResponse);
+}
+
+message GetCredentialDriverCapabilitiesRequest {
+  // Gateway protocol metadata. Drivers must reject unmet requirements.
+  openshell.extension.v1.PeerMetadata gateway = 1;
+}
+
+message GetCredentialDriverCapabilitiesResponse {
+  // Human-readable driver name.
+  string driver_name = 1;
+  // Deprecated diagnostic compatibility field. Use extension.implementation_version.
+  string driver_version = 2;
+  // Backend kind, such as "kubernetes-secrets" or "vault".
+  string backend_kind = 3;
+  // True when ListCredentials is supported.
+  bool supports_list = 4;
+  // True when ResolveCredentials may return expiration_time values.
+  bool supports_expires_at = 5;
+  // Credential-driver protocol metadata. Required for protocol negotiation.
+  // Declare protocol 1.0 and list "openshell.credentials.contract" in
+  // supported_capabilities.
+  openshell.extension.v1.PeerMetadata extension = 6;
+}
+
+message StoreCredentialRequest {
+  // Provider instance name supplied for audit and backend policy decisions.
+  string provider = 1;
+  // Gateway-owned logical key for this provider secret. Injectable credentials
+  // use their runtime environment key; refresh material uses an internal key.
+  string credential_key = 2;
+  // Secret value to store. Drivers must never log this field.
+  string value = 3;
+  // Existing handle to overwrite, if any.
+  openshell.datamodel.v1.CredentialHandle existing_handle = 4;
+  // Workspace that owns this provider. Used to ensure cross-workspace uniqueness.
+  string workspace = 5;
+  // Provider UUID. Combined with workspace to ensure globally unique backend paths.
+  string provider_id = 6;
+  // Per-write backend object identity. When empty, drivers use provider_id.
+  // Refreshes set this to a unique value so a staged write cannot overwrite the
+  // currently committed object while provider_id remains the immutable owner.
+  string object_id = 7;
+}
+
+message StoreCredentialResponse {
+  // Opaque handle for later resolution/deletion.
+  openshell.datamodel.v1.CredentialHandle handle = 1;
+}
+
+message DeleteCredentialRequest {
+  // Provider instance name supplied for audit and backend policy decisions.
+  string provider = 1;
+  // Gateway-owned logical key that owns the handle.
+  string credential_key = 2;
+  // Opaque handle to delete.
+  openshell.datamodel.v1.CredentialHandle handle = 3;
+  // Workspace that owns this provider. Used to ensure cross-workspace uniqueness.
+  string workspace = 4;
+  // Provider UUID. Combined with workspace to ensure globally unique backend paths.
+  string provider_id = 5;
+}
+
+message DeleteCredentialResponse {}
+
+message ResolveCredentialsRequest {
+  repeated ResolveCredentialRequest credentials = 1;
+}
+
+message ResolveCredentialRequest {
+  // Gateway-chosen opaque ID used to correlate batch responses.
+  string request_id = 1;
+  // Provider instance name supplied for audit and backend policy decisions.
+  string provider = 2;
+  // Gateway-owned logical key for the value being resolved.
+  string credential_key = 3;
+  // Opaque handle to resolve.
+  openshell.datamodel.v1.CredentialHandle handle = 4;
+  // Workspace that owns this provider. Used to ensure cross-workspace uniqueness.
+  string workspace = 5;
+  // Provider UUID. Combined with workspace to ensure globally unique backend paths.
+  string provider_id = 6;
+}
+
+message ResolveCredentialsResponse {
+  repeated ResolvedCredential credentials = 1;
+}
+
+message ResolvedCredential {
+  reserved 3;
+  reserved "expires_at_ms";
+  // Echoes ResolveCredentialRequest.request_id.
+  string request_id = 1;
+  // Secret string value. Drivers must never log this field.
+  string value = 2;
+  // Expiration time. Absence means the credential does not expire.
+  google.protobuf.Timestamp expiration_time = 103;
+}
+
+message ListCredentialsRequest {}
+
+message ListCredentialsResponse {
+  repeated ListedCredential credentials = 1;
+}
+
+message ListedCredential {
+  // Opaque handle identifier or driver-owned display name.
+  string handle = 1;
+  // Available credential keys under the backend object.
+  repeated string keys = 2;
+  // Driver-owned non-secret metadata.
+  map<string, string> metadata = 3;
+}

package/proto/openshell/datamodel.proto

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package openshell.datamodel.v1;
+
+import "options.proto";
+import "google/protobuf/timestamp.proto";
+
+// Selects the workspace scope for a public API request.
+//
+// Requests that operate on one workspace require a non-empty `workspace`.
+// Cross-workspace list requests additionally accept `all_workspaces`. The
+// containing request documents which selections it supports; an omitted
+// selector is invalid for workspace-scoped operations.
+message WorkspaceSelector {
+  oneof selection {
+    // One explicitly named workspace. Use `default` to select the gateway's
+    // default workspace; an empty name is invalid.
+    string workspace = 1;
+    // All workspaces the caller is authorized to access. Only supported by
+    // requests that explicitly document cross-workspace behavior.
+    AllWorkspaces all_workspaces = 2;
+  }
+}
+
+// Marker for the all-workspaces selector variant.
+message AllWorkspaces {}
+
+// Kubernetes-style metadata shared by all top-level OpenShell domain objects.
+//
+// This structure provides consistent metadata (identity, labels, annotations,
+// timestamps, resource versioning) across Sandbox, Provider, SshSession, and
+// other resources.
+message ObjectMeta {
+  reserved 3, 8;
+  reserved "created_at_ms", "deletion_timestamp_ms";
+  // Stable object ID generated by the gateway.
+  string id = 1;
+
+  // Human-readable object name (unique per object type).
+  string name = 2;
+
+  // Time when the object was created.
+  google.protobuf.Timestamp created_time = 103;
+
+  // Key-value labels for filtering and organization.
+  // Labels must follow Kubernetes conventions: alphanumeric + `-._/`, max 63 chars per segment.
+  map<string, string> labels = 4;
+
+  // Optimistic concurrency control version.
+  // Incremented by the gateway on each update. Clients can use this for compare-and-swap operations.
+  uint64 resource_version = 5;
+
+  // Opaque key-value metadata that is not used for selectors.
+  // Annotation keys use the same qualified-key shape as labels, but values may be longer.
+  map<string, string> annotations = 6;
+
+  // Workspace that owns this resource. Empty is normalized to "default" by the
+  // gateway. Immutable after creation.
+  string workspace = 7;
+
+  // Time when graceful deletion was initiated. Absence means the object is
+  // not being deleted. Once set, this field is
+  // immutable — the only path forward is completing deletion.
+  google.protobuf.Timestamp deletion_time = 108;
+}
+
+// Phase of a workspace's lifecycle.
+enum WorkspacePhase {
+  WORKSPACE_PHASE_UNSPECIFIED = 0;
+  WORKSPACE_PHASE_ACTIVE = 1;
+  WORKSPACE_PHASE_TERMINATING = 2;
+}
+
+// Status of a workspace.
+message WorkspaceStatus {
+  WorkspacePhase phase = 1;
+}
+
+// Workspace resource. A hard isolation boundary for sandboxes, providers, and
+// other workspace-scoped resources.
+message Workspace {
+  // Kubernetes-style metadata (id, name, labels, timestamps, resource version).
+  // The workspace field in this ObjectMeta is unused (a workspace does not
+  // belong to another workspace).
+  ObjectMeta metadata = 1;
+
+  // Current lifecycle status.
+  WorkspaceStatus status = 2;
+}
+
+// Opaque handle for a provider credential stored by gateway credential storage.
+// Handles are created by OpenShell and must not be authored by users.
+message CredentialHandle {
+  // Internal storage owner or credential driver that owns this handle.
+  string driver = 1;
+  // Owner-owned opaque handle string.
+  string handle = 2;
+  // Owner-owned non-secret metadata.
+  map<string, string> metadata = 3;
+}
+
+// Provider model stored by OpenShell.
+message Provider {
+  reserved 5;
+  reserved "credential_expires_at_ms";
+  // Kubernetes-style metadata (id, name, labels, timestamps, resource version).
+  ObjectMeta metadata = 1;
+  // ID of the provider profile this provider was created from, matched
+  // exactly (for example: "claude-code", "github").
+  string type = 2;
+  // Secret values used for authentication.
+  map<string, string> credentials = 3 [(openshell.options.v1.secret) = true];
+  // Non-secret provider configuration.
+  map<string, string> config = 4;
+  // Expiration times for credential values, keyed by credential/env var name.
+  // A missing key means the credential does not expire.
+  map<string, google.protobuf.Timestamp> credential_expiration_times = 105;
+  // Workspace where this provider's type profile is stored.
+  // Empty string = platform/global scope. Must be empty or match
+  // metadata.workspace; cross-workspace references are rejected.
+  string profile_workspace = 6;
+  // Opaque handles for secret values stored through gateway credential storage.
+  // This map is internal gateway state and is not accepted as user-authored input.
+  map<string, CredentialHandle> credential_handles = 7;
+}

package/proto/openshell/extension.proto

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package openshell.extension.v1;
+
+// Version of an OpenShell extension protocol contract.
+//
+// The major version changes when peers cannot safely interoperate. Minor
+// versions add optional fields or capabilities and remain compatible when both
+// peers' required capabilities are satisfied.
+message ProtocolVersion {
+  uint32 major = 1;
+  uint32 minor = 2;
+}
+
+// Non-secret metadata exchanged by the gateway and an extension before use.
+message PeerMetadata {
+  // Extension-family protocol contract version, distinct from the build.
+  ProtocolVersion protocol_version = 1;
+
+  // Stable human-readable implementation identity, such as "openshell/docker".
+  string implementation_name = 2;
+
+  // Implementation or build version used only for diagnostics.
+  string implementation_version = 3;
+
+  // Optional namespaced capabilities this peer understands.
+  repeated string supported_capabilities = 4;
+
+  // Capabilities that the opposite peer must advertise.
+  repeated string required_capabilities = 5;
+}

package/proto/openshell/options.proto

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+syntax = "proto3";
+
+package openshell.options.v1;
+
+import "google/protobuf/descriptor.proto";
+
+// Per-method authorization rule. Consumed at runtime by the gateway's
+// descriptor-pool-based auth table to enforce auth mode, role, and scope.
+message AuthorizationRule {
+  // Authentication mode: "bearer", "sandbox", "dual", "peer", "operator",
+  // or "unauthenticated". Operator requires a verified mTLS operator certificate.
+  string auth_mode = 1;
+  // Minimum workspace-level role required (checked by handler via
+  // authorize_workspace): "user" or "admin". Mutually exclusive with
+  // global_role.
+  string workspace_role = 2;
+  // Global role required (checked by middleware via OIDC claims):
+  // "platform_admin". Mutually exclusive with workspace_role.
+  string global_role = 3;
+  // Required OIDC scope on the bearer path (e.g. "sandbox:read").
+  string scope = 4;
+}
+
+extend google.protobuf.MethodOptions {
+  // Authorization metadata for a gRPC method.
+  AuthorizationRule authorization = 50000;
+}
+
+// Marks a protobuf field whose value must not cross generic observation or
+// extension boundaries such as gateway interceptors.
+extend google.protobuf.FieldOptions {
+  bool secret = 50001;
+}