@tickernelz/paperclip-pro-plugin-kubernetes 2026.925.0

package/dist/manifest.js

@@ -0,0 +1,108 @@
+const PLUGIN_ID = "paperclip.kubernetes-sandbox-provider";
+const PLUGIN_VERSION = "0.1.0-alpha.1";
+const manifest = {
+    id: PLUGIN_ID,
+    apiVersion: 1,
+    version: PLUGIN_VERSION,
+    displayName: "Kubernetes Sandbox (alpha)",
+    description: "Built on kubernetes-sigs/agent-sandbox (v1alpha1). ALPHA — expect breaking changes as the upstream CRD evolves. Falls back to stable batch/v1 Job mode for clusters without agent-sandbox installed. First-party Paperclip sandbox-provider plugin for Kubernetes.",
+    author: "Paperclip",
+    categories: ["automation"],
+    capabilities: ["environment.drivers.register"],
+    entrypoints: {
+        worker: "./dist/worker.js",
+    },
+    environmentDrivers: [
+        {
+            driverKey: "kubernetes",
+            kind: "sandbox_provider",
+            displayName: "Kubernetes",
+            description: "Dispatches agent runs in per-tenant Kubernetes namespaces. Default backend (sandbox-cr, alpha) uses kubernetes-sigs/agent-sandbox for multi-command exec; fallback backend (job) uses stable batch/v1 Job for clusters without agent-sandbox installed.",
+            configSchema: {
+                type: "object",
+                properties: {
+                    inCluster: {
+                        type: "boolean",
+                        description: "When true, the plugin uses the in-pod ServiceAccount credentials. Requires paperclip-server to be running inside the target cluster.",
+                    },
+                    kubeconfig: {
+                        type: "string",
+                        format: "secret-ref",
+                        description: "Inline kubeconfig YAML. Paste a kubeconfig or an existing Paperclip secret reference; pasted values are stored as company secrets.",
+                    },
+                    namespacePrefix: {
+                        type: "string",
+                        description: "Prefix for the per-company tenant namespace (default: paperclip-).",
+                    },
+                    companySlug: {
+                        type: "string",
+                        description: "Override the auto-derived company slug used in the tenant namespace name.",
+                    },
+                    imageRegistry: {
+                        type: "string",
+                        description: "Override the default registry for agent runtime images (default: ghcr.io/paperclip-pro).",
+                    },
+                    imageAllowList: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Glob patterns of allowed `target.imageOverride` values. Empty list = no override permitted.",
+                    },
+                    imagePullSecrets: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Names of pre-created Docker image pull secrets in the tenant namespace.",
+                    },
+                    egressAllowFqdns: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional FQDNs to allow egress to from agent pods. Adapter-default FQDNs (e.g. api.anthropic.com) are added automatically.",
+                    },
+                    egressAllowCidrs: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Additional CIDRs to allow egress to from agent pods.",
+                    },
+                    egressMode: {
+                        type: "string",
+                        enum: ["standard", "cilium"],
+                        description: "Network policy mode. `cilium` enables FQDN-based egress filtering via CiliumNetworkPolicy.",
+                    },
+                    runtimeClassName: {
+                        type: "string",
+                        description: "Optional RuntimeClass for pod isolation (e.g. `kata-fc` for Firecracker-backed microVMs). Cluster must have the RuntimeClass installed.",
+                    },
+                    serviceAccountAnnotations: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                        description: "Annotations applied to the per-tenant ServiceAccount (e.g. `eks.amazonaws.com/role-arn` for IRSA).",
+                    },
+                    jobTtlSecondsAfterFinished: {
+                        type: "integer",
+                        minimum: 0,
+                        description: "Seconds after a Job completes before it is garbage-collected (default: 900).",
+                    },
+                    podActivityDeadlineSec: {
+                        type: "integer",
+                        minimum: 1,
+                        description: "Hard ceiling on a single run's wall-clock time (default: 3600).",
+                    },
+                    adapterType: {
+                        type: "string",
+                        description: "The adapter type that Jobs in this environment will run (e.g. `claude_local`, `codex_local`). Defaults to `claude_local`. Each environment is bound to one adapter; create multiple environments for different adapters.",
+                    },
+                    backend: {
+                        type: "string",
+                        enum: ["sandbox-cr", "job"],
+                        description: "sandbox-cr (default, alpha — requires kubernetes-sigs/agent-sandbox installed) | job (stable fallback — batch/v1 Job, one-shot entrypoint, no multi-command exec)",
+                    },
+                },
+                anyOf: [
+                    { required: ["inCluster"] },
+                    { required: ["kubeconfig"] },
+                ],
+            },
+        },
+    ],
+};
+export default manifest;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/dist/network-policy.d.ts

@@ -0,0 +1,22 @@
+export interface BuildNetworkPolicyInput {
+    namespace: string;
+    paperclipServerNamespace: string;
+    egressAllowCidrs: string[];
+    /**
+     * Adapter-configured FQDNs (e.g. `api.anthropic.com`). Standard
+     * NetworkPolicy cannot express FQDNs natively — only Cilium can.
+     * When this list is non-empty AND no explicit `egressAllowCidrs`
+     * was provided, the standard NetworkPolicy falls back to "public
+     * IPv4 except RFC1918/link-local/loopback/multicast" so the
+     * configured FQDNs at least become reachable. This is broader
+     * than the operator probably wants — switch to `egressMode:
+     * "cilium"` for exact FQDN allow-listing in production.
+     */
+    egressAllowFqdns?: string[];
+    name?: string;
+    podSelector?: Record<string, string>;
+    includeBaseRules?: boolean;
+    ownerReferences?: Record<string, unknown>[];
+}
+export declare function buildNetworkPolicyManifests(input: BuildNetworkPolicyInput): Record<string, unknown>[];
+//# sourceMappingURL=network-policy.d.ts.map

package/dist/network-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-policy.d.ts","sourceRoot":"","sources":["../src/network-policy.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB,EAAE,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAC7C;AA2BD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CA6FrG"}

package/dist/network-policy.js

@@ -0,0 +1,116 @@
+/**
+ * IPv4 ranges to carve out of `0.0.0.0/0` when we apply the
+ * public-internet fallback. Keeps agent pods from reaching cluster
+ * internals (RFC1918), node link-local + AWS IMDS (169.254.0.0/16),
+ * cluster loopback (127.0.0.0/8), CGNAT (100.64.0.0/10), this-network
+ * (0.0.0.0/8), and multicast (224.0.0.0/4).
+ */
+const PRIVATE_AND_LINK_LOCAL_EXCEPT_CIDRS = [
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "100.64.0.0/10",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+    "224.0.0.0/4",
+];
+// Design note: the deny-all baseline blocks all ingress to agent pods.
+// Paperclip-server does NOT push to agent pods — the agent shim makes
+// outbound calls to paperclip-server via the egress allow-list (port 3100).
+// This pull/callback model means no ingress rule is needed. If a future
+// feature requires server→agent push (e.g. forced shutdown, live exec),
+// add a targeted ingress rule here scoped to the paperclip-server pod
+// selector.
+export function buildNetworkPolicyManifests(input) {
+    const denyAll = {
+        apiVersion: "networking.k8s.io/v1",
+        kind: "NetworkPolicy",
+        metadata: {
+            name: "paperclip-deny-all",
+            namespace: input.namespace,
+            labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+        },
+        spec: {
+            podSelector: {},
+            policyTypes: ["Ingress", "Egress"],
+        },
+    };
+    const egressAllow = {
+        apiVersion: "networking.k8s.io/v1",
+        kind: "NetworkPolicy",
+        metadata: {
+            namespace: input.namespace,
+            labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+        },
+        spec: {
+            podSelector: { matchLabels: input.podSelector ?? { "paperclip.io/role": "agent" } },
+            policyTypes: ["Egress"],
+            egress: [
+                ...(input.includeBaseRules === false ? [] : [{
+                        to: [
+                            {
+                                namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": "kube-system" } },
+                                podSelector: { matchLabels: { "k8s-app": "kube-dns" } },
+                            },
+                        ],
+                        ports: [
+                            { protocol: "UDP", port: 53 },
+                            { protocol: "TCP", port: 53 },
+                        ],
+                    }]),
+                ...(input.includeBaseRules === false ? [] : [{
+                        to: [
+                            {
+                                namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": input.paperclipServerNamespace } },
+                                podSelector: { matchLabels: { app: "paperclip-server" } },
+                            },
+                        ],
+                        ports: [{ protocol: "TCP", port: 3100 }],
+                    }]),
+                // NOTE: operator-supplied CIDRs are intentionally NOT port-scoped —
+                // operators may need them for non-HTTP services (e.g. private VCS
+                // mirrors, S3 endpoints, internal artifact registries). Operators
+                // should keep CIDRs as specific as possible. For HTTP/HTTPS-only
+                // LLM endpoints, the public-IPv4 fallback below is port-scoped
+                // (TCP 80/443).
+                ...input.egressAllowCidrs.map((cidr) => ({
+                    to: [{ ipBlock: { cidr } }],
+                })),
+                // Standard-NetworkPolicy fallback for FQDN-based egress. If the
+                // adapter requires FQDNs (e.g. api.anthropic.com) and the
+                // operator didn't supply explicit CIDRs, allow public IPv4 with
+                // private/link-local/loopback/multicast carved out. This makes
+                // the default `egressMode: "standard"` config functional out of
+                // the box for cloud LLM APIs without inadvertently exposing
+                // cluster internals or link-local metadata endpoints. Operators
+                // who want exact FQDN enforcement should use `egressMode: "cilium"`.
+                ...(input.egressAllowCidrs.length === 0 &&
+                    (input.egressAllowFqdns?.length ?? 0) > 0
+                    ? [
+                        {
+                            to: [
+                                {
+                                    ipBlock: {
+                                        cidr: "0.0.0.0/0",
+                                        except: PRIVATE_AND_LINK_LOCAL_EXCEPT_CIDRS,
+                                    },
+                                },
+                            ],
+                            ports: [
+                                { protocol: "TCP", port: 443 },
+                                { protocol: "TCP", port: 80 },
+                            ],
+                        },
+                    ]
+                    : []),
+            ],
+        },
+    };
+    egressAllow.metadata.name = input.name ?? "paperclip-egress-allow";
+    if (input.ownerReferences) {
+        egressAllow.metadata.ownerReferences = input.ownerReferences;
+    }
+    return [denyAll, egressAllow];
+}
+//# sourceMappingURL=network-policy.js.map

package/dist/network-policy.js.map

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

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+declare const plugin: import("@tickernelz/paperclip-pro-plugin-sdk").PaperclipPlugin;
+export default plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA2MA,QAAA,MAAM,MAAM,gEA8zBV,CAAC;AAEH,eAAe,MAAM,CAAC"}