edgegate-mcp 0.7.0 → 0.9.0

package/dist/tools/register_byo_bucket.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { EdgeGateError } from "../client.js";
+export const registerByoBucketInputSchema = z.object({
+    workspace_id: z.string().uuid(),
+    role_arn: z
+        .string()
+        .regex(/^arn:aws:iam::\d{12}:role\/.+$/)
+        .describe("ARN of the IAM role EdgeGate's workers will assume to read your bucket. " +
+        "Created by the EdgeGate CloudFormation launch stack (or your equivalent " +
+        "Terraform module). Format: arn:aws:iam::<account-id>:role/<name>."),
+    bucket: z
+        .string()
+        .min(3)
+        .max(255)
+        .regex(/^[a-z0-9][a-z0-9\-.]{1,253}$/)
+        .describe("S3 bucket name (not the URI — just the bucket name)."),
+    region: z
+        .string()
+        .min(4)
+        .max(64)
+        .describe("AWS region the bucket lives in, e.g. us-east-1."),
+    kms_key_id: z
+        .string()
+        .max(2048)
+        .optional()
+        .describe("Optional KMS key ARN if the bucket uses SSE-KMS. The IAM role must " +
+        "have kms:Decrypt on this key."),
+});
+export async function registerByoBucketHandler(client, input) {
+    try {
+        const grant = await client.registerByoGrant(input.workspace_id, {
+            role_arn: input.role_arn,
+            bucket: input.bucket,
+            region: input.region,
+            kms_key_id: input.kms_key_id,
+        });
+        return successText(grant);
+    }
+    catch (err) {
+        if (err instanceof EdgeGateError) {
+            if (err.status === 402) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `BYO storage requires the **Enterprise plan**.`,
+                                ``,
+                                `Reach out to sales at https://edgegate.frozo.ai/enterprise ` +
+                                    `to enable BYO storage on this workspace. ` +
+                                    `Once enabled, re-run \`edgegate_register_byo_bucket\` with the ` +
+                                    `same role + bucket details.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            if (err.status === 409) {
+                // Do NOT auto-rotate — the existing grant may belong to a different
+                // role_arn the customer doesn't want overwritten by accident.
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `This workspace already has a BYO storage grant registered.`,
+                                ``,
+                                `Two safe paths forward:`,
+                                `1. Inspect the existing grant with \`edgegate_check_byo_bucket\` ` +
+                                    `to confirm it's the one you intended.`,
+                                `2. If you want to replace it: \`edgegate_disconnect_byo_bucket\` ` +
+                                    `first (will 409 if artifacts still reference it), then re-run ` +
+                                    `\`edgegate_register_byo_bucket\` with the new role/bucket.`,
+                                ``,
+                                `External-ID rotation (without replacing the grant) is available ` +
+                                    `via the dashboard at ` +
+                                    `https://edgegate.frozo.ai/workspace/${input.workspace_id}/settings#byo-storage.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `EdgeGate returned ${err.status}: ${err.detail}`,
+                    },
+                ],
+            };
+        }
+        throw err;
+    }
+}
+function roleArnTail(roleArn) {
+    // arn:aws:iam::123456789012:role/edgegate-byo-storage-prod
+    // Render the trailing role name + last 4 of the account id so the user can
+    // confirm at a glance that they registered the right role.
+    const parts = roleArn.split(":");
+    if (parts.length < 6)
+        return roleArn;
+    const account = parts[4];
+    const roleName = parts.slice(5).join(":").replace(/^role\//, "");
+    const acctTail = account.length > 4 ? `…${account.slice(-4)}` : account;
+    return `${roleName} (acct ${acctTail})`;
+}
+function successText(grant) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    `Registered BYO storage grant for this workspace.`,
+                    ``,
+                    `- role: \`${roleArnTail(grant.role_arn)}\``,
+                    `- bucket: \`${grant.bucket}\` (${grant.region})`,
+                    grant.kms_key_id
+                        ? `- kms key: \`${grant.kms_key_id}\``
+                        : `- kms key: (none — SSE-S3 or no encryption)`,
+                    `- status: **${grant.status}**`,
+                    `- external_id: \`${grant.external_id}\``,
+                    ``,
+                    `**Action required if you haven't already:** add this External ID to ` +
+                        `your IAM role's trust policy under \`Condition.StringEquals.sts:ExternalId\`. ` +
+                        `Without it, AssumeRole will fail with BYO_ASSUME_ROLE_FAILED.`,
+                    ``,
+                    grant.status === "active"
+                        ? `The readiness probe just passed. You can register your first artifact ` +
+                            `with \`edgegate_register_byo_artifact\`.`
+                        : grant.last_verify_error
+                            ? `The readiness probe FAILED: \`${grant.last_verify_error}\`. Fix the ` +
+                                `IAM/bucket/KMS configuration, then re-probe with ` +
+                                `\`edgegate_check_byo_bucket\`.`
+                            : `Probe outcome pending — run \`edgegate_check_byo_bucket\` to verify.`,
+                ].join("\n"),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=register_byo_bucket.js.map

package/dist/tools/register_byo_bucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register_byo_bucket.js","sourceRoot":"","sources":["../../src/tools/register_byo_bucket.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -162,6 +162,19 @@ export interface APIKeyListItem {
     revoked_at: string | null;
     created_at: string;
 }
+export type DeviceCategory = "smartphone" | "reference" | "compute" | "iot" | "automotive" | "xr" | "other";
+export interface DeviceEntry {
+    /** Short alias EdgeGate uses (e.g. 'sm8650'). Stable across pipeline configs. */
+    id: string;
+    /** Canonical AI Hub device name (e.g. 'Samsung Galaxy S24 (Family)'). */
+    name: string;
+    /** Form-factor / use case bucket. */
+    category: DeviceCategory;
+}
+export interface DeviceListResponse {
+    devices: DeviceEntry[];
+    total: number;
+}
 export type WorkspaceRole = "owner" | "admin" | "viewer";
 export interface Member {
     user_id: UUID;
@@ -269,3 +282,88 @@ export interface PromptPackCreateBody {
     version: string;
     content: PromptPackContent;
 }
+/**
+ * Workspace's customer-owned S3 bucket grant. Returned by every grant
+ * endpoint (register / get / verify / rotate-external-id).
+ *
+ * `external_id` is shown in EVERY response — it's the value the customer
+ * has to paste into their IAM role trust policy's `sts:ExternalId`
+ * condition. We don't treat it like a secret because the trust policy
+ * already pins our AWS account as the only principal that can use it.
+ *
+ * `status` semantics: "active" = last probe passed; "failed" = last probe
+ * raised (with `last_verify_error` populated); "revoked" = grant was
+ * explicitly deleted (404 on /grants thereafter).
+ */
+export interface ByoGrant {
+    id: UUID;
+    workspace_id: UUID;
+    role_arn: string;
+    external_id: UUID;
+    bucket: string;
+    region: string;
+    kms_key_id: string | null;
+    status: "active" | "revoked" | "failed";
+    last_verified_at: string | null;
+    last_verify_error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Request body for POST /v1/workspaces/{ws}/artifacts/byo.
+ * Registers an existing S3 URI in the customer's grant-registered bucket
+ * as an Artifact pointer. EdgeGate does NOT upload bytes — it HeadObjects
+ * the URI to confirm existence + capture size/etag.
+ */
+export interface ByoArtifactRegisterRequest {
+    s3_uri: string;
+    expected_sha256?: string;
+    expected_size?: number;
+    kind?: string;
+    original_filename?: string;
+}
+/**
+ * One row from the workspace's append-only `byo_storage_audit` table.
+ * `aws_request_id` is the join key for cross-referencing the customer's
+ * own CloudTrail. Nullable fields are by design for events that don't
+ * produce them (verify_probe has no run_id/artifact_id, etc.).
+ */
+export interface ByoAuditEntry {
+    id: number;
+    event_type: string;
+    aws_request_id: string;
+    role_arn: string;
+    bucket: string;
+    s3_key: string | null;
+    bytes_read: number | null;
+    worker_hostname: string | null;
+    outcome: string;
+    error_code: string | null;
+    artifact_id: UUID | null;
+    run_id: UUID | null;
+    ts: string;
+}
+/**
+ * Paginated audit-log page. `next_cursor === null` means the response
+ * contained the last page. Pass the value back as the `cursor` query
+ * param to fetch the next page.
+ */
+export interface ByoAuditPage {
+    entries: ByoAuditEntry[];
+    next_cursor: number | null;
+}
+/**
+ * Returned by POST /artifacts and POST /artifacts/byo. Mirrors the
+ * backend `ArtifactResponse` schema. `storage_url` for BYO artifacts is
+ * `byo-s3://{bucket}/{key}` rather than the managed `s3://...` form.
+ */
+export interface ArtifactResponse {
+    id: UUID;
+    kind: string;
+    sha256: string;
+    size_bytes: number;
+    original_filename: string | null;
+    storage_url: string;
+    created_at: string;
+    expires_at: string | null;
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.7.0";
-export declare const USER_AGENT = "edgegate-mcp/0.7.0";
+export declare const VERSION = "0.9.0";
+export declare const USER_AGENT = "edgegate-mcp/0.9.0";

package/dist/version.js

@@ -1,3 +1,3 @@
-export const VERSION = "0.7.0";
+export const VERSION = "0.9.0";
 export const USER_AGENT = `edgegate-mcp/${VERSION}`;
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edgegate-mcp",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "MCP server for EdgeGate — set up edge-AI regression gates from Claude Code, Cursor, or Claude Desktop.",
   "license": "MIT",
   "type": "module",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "edgegate",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Edge-AI regression gates from Claude Code — set up CI, run benchmarks, compare runs, export reports, and fetch audit bundles from any prompt.",
   "author": "Frozo / EdgeGate",
   "homepage": "https://edgegate.frozo.ai",
@@ -29,6 +29,7 @@
     "skills/edgegate-connect-huggingface.md",
     "skills/edgegate-connect-qaihub.md",
     "skills/edgegate-workspace-setup.md",
-    "skills/edgegate-members.md"
+    "skills/edgegate-members.md",
+    "skills/edgegate-byo-storage.md"
   ]
 }

package/skills/edgegate-byo-storage.md

@@ -0,0 +1,148 @@
+---
+name: edgegate-byo-storage
+description: Wire up BYO (bring-your-own) S3 storage for an Enterprise EdgeGate workspace — register the IAM role + bucket grant, verify the readiness probe, register the first artifact directly from the customer's bucket, and confirm the audit trail. Use when the user is on the Enterprise plan and wants model bytes to live in their own AWS account.
+---
+
+# /edgegate-byo-storage
+
+This is the **Enterprise BYO storage onboarding** flow. The whole point of
+BYO is that model bytes never leave the customer's AWS account — EdgeGate's
+workers AssumeRole into their account and read directly from their bucket.
+
+Use this skill once per workspace, after the customer's security/IAM team
+has provisioned the role + bucket.
+
+## When to use
+
+- The workspace is on the **Enterprise plan** (BYO storage 402s otherwise).
+- The user has (or wants to provision) their own S3 bucket and IAM role.
+- The user is migrating an existing workspace from EdgeGate-managed storage
+  to BYO, or onboarding a brand-new Enterprise workspace.
+
+If the workspace isn't Enterprise yet, send them to
+<https://edgegate.frozo.ai/enterprise> first — none of the
+`edgegate_*_byo_*` tools will work until BYO is enabled on the plan.
+
+## Pre-flight (AWS side — the user does this in their account)
+
+You can't do this part for them, but you can hand them the exact spec:
+
+1. **Provision the IAM role.** The fastest path is the EdgeGate
+   CloudFormation Launch Stack — link them to it from
+   <https://edgegate.frozo.ai/workspace/{workspace_id}/settings#byo-storage>.
+   (A Terraform module is also published; ask the customer which their
+   security team prefers.) The stack creates:
+   - The IAM role with `sts:AssumeRole` trusted to EdgeGate's AWS account.
+   - The S3 bucket policy granting that role `s3:GetObject` + `ListBucket`
+     scoped to the bucket only.
+   - (Optional) KMS key policy granting `kms:Decrypt` if the bucket uses
+     SSE-KMS.
+2. **Capture** the `role_arn`, `bucket` name, `region`, and (if applicable)
+   `kms_key_id`. The trust policy's `sts:ExternalId` is left as a
+   placeholder — EdgeGate mints the real one in step 1 below and the
+   customer pastes it back.
+
+If they want the raw IAM JSON instead of CloudFormation/Terraform, point
+them at `docs/byo-storage-onboarding.md` in the backend repo or the
+dashboard's "Show raw policies" link.
+
+## Steps
+
+1. **Register the grant.** Call
+   `edgegate_register_byo_bucket({ workspace_id, role_arn, bucket, region, kms_key_id? })`.
+   The response includes an `external_id` UUID — capture it.
+
+2. **Paste the External ID into the IAM role trust policy.** Tell the
+   user, in plain English: "Open your IAM role in the AWS console, edit
+   the trust relationship, and replace the placeholder ExternalId with
+   `<external_id>`." Until they do this, AssumeRole will fail with
+   `BYO_ASSUME_ROLE_FAILED`.
+
+   The CloudFormation stack supports passing the External ID as a
+   parameter — point them at that if they used the stack.
+
+3. **Verify the probe.** After the user confirms the trust policy edit
+   is saved, call `edgegate_check_byo_bucket({ workspace_id })`. Expect
+   `status: "active"`. If `status: "failed"`, the response's checklist
+   covers every typed `BYO_*` error code — read the `last_verify_error`
+   to the user, suggest the matching fix, then re-run `check`.
+
+4. **Register the first artifact.** Pick (or ask for) an existing model
+   in the bucket. Call:
+   ```
+   edgegate_register_byo_artifact({
+     workspace_id,
+     s3_uri: "s3://<bucket>/<key>.onnx",
+     expected_sha256: "<optional but recommended>",
+   })
+   ```
+   Capture the returned `artifact_id`. EdgeGate did NOT download the
+   bytes — it only HeadObject'd the URI to confirm the key exists and
+   capture size + etag. The storage URL in the response will start with
+   `byo-s3://` (not `s3://`) — that's how downstream tooling routes
+   reads through the BYO service rather than EdgeGate's managed S3.
+
+5. **Trigger the first run.** Run the artifact against an existing
+   pipeline so the customer sees the end-to-end flow work:
+   ```
+   edgegate_run_gate({
+     workspace_id,
+     pipeline_id: "<existing pipeline>",
+     model_artifact_id: "<artifact_id from step 4>",
+   })
+   ```
+   Poll with `edgegate_check_status` until it terminates.
+
+6. **Show them the audit trail.** Call
+   `edgegate_get_byo_audit({ workspace_id, run_id: "<run_id from step 5>" })`.
+   The table includes one row per S3 / STS call with the
+   `aws_request_id`. Tell the user: "Cross-reference these against your
+   own CloudTrail in the same time window — every read should match."
+   This is the trust handshake the customer's security team will ask
+   for.
+
+7. **Recap + next.** Summarize:
+   - Grant: `active`, bucket=`<name>`, region=`<region>`
+   - First artifact registered + first run executed
+   - Audit log accessible via `edgegate_get_byo_audit`
+
+   Next concrete actions:
+   - "Migrate more artifacts: `edgegate_register_byo_artifact` per s3_uri"
+   - "Schedule periodic audit pulls into your SIEM (we can stream via API)"
+   - "Rotate the External ID at any time via the dashboard"
+
+## Failure modes
+
+- **Register grant → 402.** Workspace is not on Enterprise. Send them to
+  <https://edgegate.frozo.ai/enterprise>.
+- **Register grant → 409.** A grant already exists. We deliberately do
+  NOT auto-rotate — the existing grant may belong to a role the customer
+  doesn't want overwritten. Inspect with `edgegate_check_byo_bucket`,
+  then either keep it or `edgegate_disconnect_byo_bucket` and re-register.
+  External-ID-only rotation is available via the dashboard.
+- **Check probe → status=failed with BYO_ASSUME_ROLE_FAILED.** External
+  ID drift between EdgeGate and the role's trust policy. Re-paste the
+  current external_id (visible via `edgegate_check_byo_bucket` or the
+  dashboard) into the trust policy's `sts:ExternalId` condition.
+- **Check probe → BYO_KMS_ACCESS_DENIED.** SSE-KMS bucket but the role
+  is missing `kms:Decrypt` on the key. Add the role principal to the
+  KMS key policy.
+- **Check probe → BYO_REGION_MISMATCH.** The bucket lives in a different
+  region than the `region` you registered. Disconnect and re-register
+  with the correct region.
+- **Register artifact → 400 bucket mismatch.** The s3_uri points at a
+  bucket that isn't this workspace's registered one. Cross-bucket
+  pointers are forbidden — register the right bucket (or move the
+  object).
+- **Register artifact → 400 BYO_OBJECT_NOT_FOUND.** The key is mistyped
+  or the role's bucket policy denies `ListBucket`/`GetObject` on that
+  prefix. HeadObject failures pass through with the typed code.
+- **Disconnect → 409.** Artifacts still reference the grant. The
+  response lists the safe paths forward (drop the artifacts first, or
+  rotate the External ID via dashboard if that's what you actually
+  wanted).
+- **Mid-run revocation** (customer revokes the role mid-run): the
+  in-flight cells complete, the rest fail with
+  `BYO_ASSUME_ROLE_FAILED`, the run terminates as `failed` (not
+  `error`) with the partial-success cells preserved in the bundle.
+  This is by design — re-grant + re-run picks up cleanly.