OpenShell/proto/datamodel.proto

// 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";

// 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 {
  // Stable object ID generated by the gateway.
  string id = 1;

  // Human-readable object name (unique per object type).
  string name = 2;

  // Milliseconds since Unix epoch when the object was created.
  int64 created_at_ms = 3;

  // 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;

  // Milliseconds since Unix epoch when graceful deletion was initiated.
  // Zero means the object is not being deleted. Once set, this field is
  // immutable — the only path forward is completing deletion.
  int64 deletion_timestamp_ms = 8;
}

// 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 {
  // Kubernetes-style metadata (id, name, labels, timestamps, resource version).
  ObjectMeta metadata = 1;
  // Canonical provider type slug (for example: "claude", "gitlab").
  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 timestamps for credential values, keyed by credential/env var
  // name. A zero or missing value means the credential does not expire.
  map<string, int64> credential_expires_at_ms = 5;
  // 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;
}