@singularity-layer/cli 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -79,8 +79,55 @@ singularity processors env list # which are declared, which are
79
79
  singularity processors env unset OPENAI_API_KEY
80
80
  ```
81
81
 
82
- Values are write-only. They are never returned — not to you, not to your code — and the egress
83
- gateway injects them into outbound requests to the host you bound them to.
82
+ Values are write-only *to you*: we never hand one back through the API.
83
+
84
+ **Two modes, chosen per secret.** The default is the strong one:
85
+
86
+ ```json
87
+ "secrets": [
88
+ { "name": "OPENAI_API_KEY", "hosts": ["api.openai.com"],
89
+ "inject": { "header": "Authorization", "format": "Bearer {value}" } },
90
+ { "name": "SIGNING_KEY", "mode": "env" }
91
+ ]
92
+ ```
93
+
94
+ `inject` (the default) — **the value never enters your isolate.** You call `fetch()` with no
95
+ credential and the egress gateway adds the header server-side, for the hosts you declared and nowhere
96
+ else. Code that never holds a key cannot leak the key.
97
+
98
+ `mode: "env"` — **your code holds the value**, via `await SGL.secrets.get('SIGNING_KEY')`. This is a
99
+ real downgrade and it is opt-in for exactly that reason: once your code has the value it can print it
100
+ into your logs, or send it to any host in your egress allowlist, and we cannot stop either. Use it
101
+ only for credentials that genuinely cannot be an outbound header — a key you sign with locally, or a
102
+ value an SDK insists on reading itself. The alternative most people reach for otherwise is
103
+ hard-coding the secret in their source, which is worse in every way.
104
+
105
+ `singularity processors env list` shows which of yours is which.
106
+
107
+ ## Processor state
108
+
109
+ A processor is a fresh isolate every run, so anything you want to keep has to go somewhere:
110
+
111
+ ```js
112
+ // Key/value — a cursor, a cache, a dedupe set. Values are opaque strings, byte-exact.
113
+ await SGL.kv.put('cursor', '2026-08-12');
114
+ const cursor = await SGL.kv.get('cursor');
115
+
116
+ // Compare-and-swap, for a counter or a lock. Concurrent runs are the normal case.
117
+ const cur = await SGL.kv.getWithVersion('count');
118
+ await SGL.kv.put('count', String(Number(cur.value) + 1), { ifVersion: cur.version });
119
+
120
+ // Objects — a generated PDF, an image, a dataset.
121
+ await SGL.files.put('reports/august.pdf', bytes, { contentType: 'application/pdf' });
122
+ const { url } = await SGL.files.downloadUrl('reports/august.pdf', { ttlSeconds: 3600 });
123
+ ```
124
+
125
+ `downloadUrl` gives you a signed, expiring link a buyer can fetch with **no credential**. It is
126
+ always served as an attachment with a forced `application/octet-stream` type — your declared type is
127
+ never echoed — so a stored HTML or SVG file cannot execute. Treat it as a bearer link: anyone who
128
+ gets it can download until it expires.
129
+
130
+ None of this needs an `egress.allow` entry. It is not the network.
84
131
 
85
132
  ### Turning it off without losing it
86
133
 
package/dist/cli.js CHANGED
@@ -460,6 +460,15 @@ var emit = (flags, value) => {
460
460
  console.log(JSON.stringify(value, null, 2));
461
461
  return true;
462
462
  };
463
+ function warnEnvSecrets(manifest) {
464
+ const envNames = (manifest.secrets ?? []).filter((s) => s.mode === "env").map((s) => s.name);
465
+ if (!envNames.length) return;
466
+ ok("");
467
+ ok(`note: ${envNames.join(", ")} ${envNames.length === 1 ? "is" : "are"} declared mode: "env".`);
468
+ ok(" Your code can read the value. That means it can also print it into your logs, or send");
469
+ ok(' it to any host in your egress allowlist \u2014 we cannot stop either. Use "inject" for');
470
+ ok(" anything that is only ever an outbound header.");
471
+ }
463
472
  async function resolveSource(manifest, flags) {
464
473
  const entryPath = resolve(String(flags.entry || manifest.$entry || manifest.$code || "processor.js"));
465
474
  if (!existsSync3(entryPath)) die(`no code at ${entryPath}`);
@@ -634,6 +643,7 @@ async function run(words, flags) {
634
643
  ok();
635
644
  ok(`try it: singularity processors run '{"hello":"world"}'`);
636
645
  ok("go live: singularity processors publish");
646
+ warnEnvSecrets(manifest);
637
647
  break;
638
648
  }
639
649
  case "update": {
@@ -650,6 +660,7 @@ async function run(words, flags) {
650
660
  if (emit(flags, res)) break;
651
661
  ok(`updated ${slug} (config_rev ${res.config_rev})`);
652
662
  if (res.note) ok(res.note);
663
+ warnEnvSecrets(manifest);
653
664
  break;
654
665
  }
655
666
  case "run":
@@ -732,7 +743,9 @@ async function run(words, flags) {
732
743
  );
733
744
  if (emit(flags, res)) break;
734
745
  ok(`secrets set: ${res.secrets.join(", ") || "(none)"}`);
735
- ok("values are write-only \u2014 never returned, injected on egress");
746
+ ok("values are write-only here \u2014 we never return them to you");
747
+ if (existsSync3("processor.json")) warnEnvSecrets(loadManifest(flags));
748
+ else ok("run `singularity processors env list` to see which are injected and which your code reads");
736
749
  break;
737
750
  }
738
751
  case "env": {
@@ -740,24 +753,26 @@ async function run(words, flags) {
740
753
  const slug = requireSlug(flags);
741
754
  const action = words[1] || "list";
742
755
  if (action === "list") {
743
- const d = await api(
744
- BASE,
745
- "GET",
746
- `/processors/${slug}`,
747
- { kp }
748
- );
756
+ const d = await api(BASE, "GET", `/processors/${slug}`, { kp });
749
757
  const declared = d.manifest?.secrets ?? [];
750
758
  const set = new Set(d.secret_keys ?? []);
751
- if (emit(flags, { declared: declared.map((s) => s.name), set: [...set] })) break;
759
+ const modes = d.secret_modes ?? {};
760
+ if (emit(flags, { declared: declared.map((s) => s.name), set: [...set], modes })) break;
752
761
  if (!declared.length) {
753
762
  ok("no secrets declared \u2014 add them to manifest.secrets, then set values");
754
763
  break;
755
764
  }
756
765
  for (const s of declared) {
757
- ok(`${set.has(s.name) ? "set " : "unset "} ${s.name.padEnd(28)} ${s.host ? `-> ${s.host}` : ""}`);
766
+ const mode = modes[s.name] ?? s.mode ?? "inject";
767
+ const where = mode === "env" ? "readable by your code" : `injected -> ${(s.hosts ?? []).join(", ") || s.host || "(no host)"}`;
768
+ ok(`${set.has(s.name) ? "set " : "unset "} ${s.name.padEnd(24)} ${mode.padEnd(7)} ${where}`);
758
769
  }
759
770
  ok("");
760
- ok("values are never readable, by you or by your code \u2014 they are injected on egress");
771
+ ok("inject the value never enters your isolate; the gateway adds the header for you");
772
+ if (Object.values(modes).includes("env")) {
773
+ ok("env YOUR CODE HOLDS THIS VALUE. Printing it puts it in your logs, and we");
774
+ ok(" cannot stop it being sent anywhere your egress allowlist permits.");
775
+ }
761
776
  break;
762
777
  }
763
778
  if (action === "unset") {
@@ -986,7 +1001,7 @@ async function followLogs(base, slug, kp, limit) {
986
1001
  }
987
1002
 
988
1003
  // src/version.ts
989
- var VERSION = "0.2.0";
1004
+ var VERSION = "0.2.1";
990
1005
 
991
1006
  // src/cli.ts
992
1007
  var COMMANDS = {
package/dist/index.js CHANGED
@@ -294,7 +294,7 @@ function coerce(raw, type) {
294
294
  }
295
295
 
296
296
  // src/version.ts
297
- var VERSION = "0.2.0";
297
+ var VERSION = "0.2.1";
298
298
  export {
299
299
  MAX_BUNDLE_BYTES,
300
300
  VERSION,
package/dist/version.d.ts CHANGED
@@ -8,4 +8,4 @@
8
8
  *
9
9
  * Kept in sync with package.json by the release workflow, which is the only thing that bumps either.
10
10
  */
11
- export declare const VERSION = "0.2.0";
11
+ export declare const VERSION = "0.2.1";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@singularity-layer/cli",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Singularity developer CLI \u2014 deploy paid endpoints (Processors) on the Singularity Cloud Network",
5
5
  "type": "module",
6
6
  "bin": {