@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 +49 -2
- package/dist/cli.js +26 -11
- package/dist/index.js +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +1 -1
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
|
|
83
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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("
|
|
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.
|
|
1004
|
+
var VERSION = "0.2.1";
|
|
990
1005
|
|
|
991
1006
|
// src/cli.ts
|
|
992
1007
|
var COMMANDS = {
|
package/dist/index.js
CHANGED
package/dist/version.d.ts
CHANGED