@future-unknown/known 0.0.0-stage → 0.2.0

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.
@@ -0,0 +1,85 @@
1
+ /**
2
+ * `known <org> …` — everything scoped to one organization.
3
+ *
4
+ * The org is the first argument, and because a token is issued by one API for one
5
+ * org, naming it picks the environment too. Qualify it as `<org>@<env>` when the
6
+ * same org is signed in on more than one environment.
7
+ *
8
+ * known <org> the commands available for that org
9
+ * known <org> ping prove the session works, end to end
10
+ * known <org> post add authored content to the org's stream
11
+ * known <org> code source trees held in Known
12
+ * known <org> sites sites that sign the org's people in with Known
13
+ * known <org> teams the org's teams
14
+ * known <org> members the org's people, invitations and requests to join
15
+ * known <org> audit who changed what in the org, and when (org owners)
16
+ * known <org> feedback tell Known's team what got in the way
17
+ * known <org> whoami who you are in that org
18
+ * known <org> logout sign out of it
19
+ * known <org> rpc <method> call a JSON-RPC method as it
20
+ *
21
+ * A first argument matching a root command (`login`, `sessions`, `ping`, …) is
22
+ * dispatched as that command, never as an org — so an org whose slug collides
23
+ * with one is not addressable here.
24
+ */
25
+ const output = require("../output")
26
+ const config = require("../config")
27
+
28
+ // Verbs take (argv, orgRef, rest) so the same module serves both the org-first
29
+ // form and the bare root form, where the org is resolved from context instead.
30
+ const verbs = {
31
+ ping: require("./_ping"),
32
+ post: require("./_post"),
33
+ wiki: require("./_wiki"),
34
+ code: require("./_code"),
35
+ sites: require("./_sites"),
36
+ teams: require("./_teams"),
37
+ members: require("./_members"),
38
+ audit: require("./_audit"),
39
+ feedback: require("./_feedback"),
40
+ whoami: require("./_whoami"),
41
+ logout: require("./_logout"),
42
+ rpc: require("./_rpc")
43
+ }
44
+
45
+ // Local, no network — so it works whether or not the org resolves to a session.
46
+ function showMenu(ref) {
47
+ const matches = config.matchSessions(ref)
48
+ const known = matches.length === 1 ? matches[0] : null
49
+
50
+ console.log()
51
+ console.log(" known ".cyan + ref.cyan + (known
52
+ ? (" " + [known.endpoint, known.role].filter(Boolean).join(" · ")).grey
53
+ : " not signed in — run `known login`".grey))
54
+ console.log()
55
+ output.commands([
56
+ [ref + " ping", "prove the session works (token, membership, policy)"],
57
+ [ref + " post [--text|--file]", "post a note into the org's stream"],
58
+ [ref + " wiki [<cmd>]", "the org's wikis: pages (read, write, edit, …) and records (get, set, …)"],
59
+ [ref + " code [<cmd>]", "source trees held in Known: files (read, write, edit, …), packages, changes, checks"],
60
+ [ref + " sites [<cmd>]", "sites that sign the org's people in with Known"],
61
+ [ref + " teams [<cmd>]", "the org's teams: people grouped to be granted wikis together"],
62
+ [ref + " members [<cmd>]", "the org's people: owners and members, invitations, requests to join"],
63
+ [ref + " audit", "the org's audit log: who changed people, teams, access and settings, and when (org owners)"],
64
+ [ref + " feedback <kind> \"…\"", "tell Known's team what got in the way (bug, missing, confusing, idea)"],
65
+ [ref + " whoami", "who you are in this org"],
66
+ [ref + " logout", "sign out of this org"],
67
+ [ref + " rpc [<method>]", "call a JSON-RPC method directly; alone, list every method the API answers"]
68
+ ])
69
+ console.log()
70
+ process.exit(0)
71
+ }
72
+
73
+ module.exports = function (argv) {
74
+ const ref = argv._[0]
75
+ const verb = argv._[1]
76
+
77
+ if (!verb) return showMenu(ref)
78
+
79
+ const handler = verbs[verb]
80
+ if (!handler) {
81
+ output.info(require("../helpers").unknownCommand("", verb, Object.keys(verbs)).grey)
82
+ return showMenu(ref)
83
+ }
84
+ return handler(argv, ref, argv._.slice(2))
85
+ }
package/lib/config.js ADDED
@@ -0,0 +1,297 @@
1
+ /**
2
+ * Session store for known.
3
+ *
4
+ * A session is one browser sign-in: an endpoint, an organization, an account,
5
+ * and the tokens that prove it. Those four are inseparable — a token is issued
6
+ * by one API for one org — so the endpoint is recorded *with* the token and is
7
+ * never a separate mode you switch. There is no global state at all:
8
+ *
9
+ * ~/.known/prod/acme.json 0600 — endpoint, org, account, role, tokens
10
+ * ~/.known/prod/globex.json
11
+ * ~/.known/staging/acme.json
12
+ *
13
+ * One file per session, so signing out of a project is a file delete, two
14
+ * concurrent sign-ins can never clobber each other, and every secret carries its
15
+ * own owner-only mode.
16
+ *
17
+ * The directory is a display *label* derived from the endpoint (its alias when
18
+ * it is a named environment, otherwise its host). The canonical URL lives inside
19
+ * each session file, so the label never has to be reversed into a URL.
20
+ *
21
+ * Sessions are addressed by org slug, and qualified as `<org>@<env>` when the
22
+ * same org is signed in on more than one environment. Because each session is
23
+ * its own sign-in, different orgs may be different Known accounts — that is the
24
+ * point: one machine can hold separate identities for separate projects.
25
+ */
26
+ const fs = require("fs")
27
+ const path = require("path")
28
+ const os = require("os")
29
+
30
+ // Named environments, accepted anywhere an endpoint is (`known login --endpoint
31
+ // staging`), and the endpoint `known login` uses when none is given. They are
32
+ // the SDK's: where Known lives is said once, there. An alias expands to its URL
33
+ // at the point of entry, so only canonical URLs are ever recorded in a session
34
+ // file.
35
+ const { ENDPOINTS, DEFAULT_ENDPOINT, expandEndpoint, aliasOf } = require("@future-unknown/known-sdk")
36
+
37
+ // Session filenames are built from an org reference, so the reference must never
38
+ // be able to escape its environment directory.
39
+ const SAFE_NAME = /^[A-Za-z0-9._-]+$/
40
+
41
+ function configDir() {
42
+ return path.join(os.homedir(), ".known")
43
+ }
44
+
45
+ // The directory label for an endpoint: its alias, else its host (plus port).
46
+ // Cosmetic — every session file records the canonical URL it belongs to.
47
+ function envLabel(endpoint) {
48
+ const alias = aliasOf(endpoint)
49
+ if (alias) return alias
50
+ try {
51
+ const u = new URL(endpoint)
52
+ return (u.port ? u.hostname + "_" + u.port : u.hostname).replace(/[^A-Za-z0-9._-]/g, "-")
53
+ } catch (e) {
54
+ return String(endpoint).replace(/[^A-Za-z0-9._-]/g, "-")
55
+ }
56
+ }
57
+
58
+ function envDir(endpoint) {
59
+ return path.join(configDir(), envLabel(endpoint))
60
+ }
61
+
62
+ // Validate an org reference before it becomes a path segment.
63
+ function safeName(ref) {
64
+ const name = String(ref == null ? "" : ref).trim()
65
+ if (!name || name === "." || name === ".." || !SAFE_NAME.test(name)) {
66
+ const e = new Error("invalid org reference: " + (name || "(empty)"))
67
+ e.friendly = true
68
+ throw e
69
+ }
70
+ return name
71
+ }
72
+
73
+ // Sessions hold access + refresh tokens, so every directory is 0700 and every
74
+ // file 0600.
75
+ function ensureDir(dir) {
76
+ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
77
+ return dir
78
+ }
79
+
80
+ function readJson(file) {
81
+ try {
82
+ return JSON.parse(fs.readFileSync(file, "utf8"))
83
+ } catch (e) {
84
+ return null
85
+ }
86
+ }
87
+
88
+ function writeJson(file, obj) {
89
+ ensureDir(path.dirname(file))
90
+ fs.writeFileSync(file, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 })
91
+ // writeFileSync's mode only applies on creation; enforce it on existing files.
92
+ try { fs.chmodSync(file, 0o600) } catch (e) {}
93
+ return obj
94
+ }
95
+
96
+ function sessionFile(endpoint, org) {
97
+ return path.join(envDir(endpoint), safeName(org) + ".json")
98
+ }
99
+
100
+ // ---- reading sessions -------------------------------------------------------
101
+
102
+ // Decorate a stored session with how it is addressed: `key` is the org it is
103
+ // filed under, `env` the environment label, `label` the qualified `<org>@<env>`.
104
+ function decorate(data, key) {
105
+ return {
106
+ ...data,
107
+ key,
108
+ env: data.endpoint ? envLabel(data.endpoint) : null,
109
+ label: key + "@" + (data.endpoint ? envLabel(data.endpoint) : "?")
110
+ }
111
+ }
112
+
113
+ // Every session stored for one endpoint, newest sign-in first.
114
+ function listSessions(endpoint) {
115
+ const dir = envDir(endpoint)
116
+ let names
117
+ try {
118
+ names = fs.readdirSync(dir)
119
+ } catch (e) {
120
+ return []
121
+ }
122
+ return names
123
+ .filter((n) => n.endsWith(".json"))
124
+ .map((n) => {
125
+ const data = readJson(path.join(dir, n))
126
+ if (!data || !data.access_token) return null
127
+ return decorate(data, n.slice(0, -5))
128
+ })
129
+ .filter(Boolean)
130
+ .filter((s) => !s.endpoint || s.endpoint === endpoint)
131
+ .sort((a, b) => String(b.created_at || "").localeCompare(String(a.created_at || "")))
132
+ }
133
+
134
+ // Every session on this machine, across every environment. This is the whole
135
+ // store: there is no "current" anything to consult first.
136
+ function allSessions() {
137
+ let labels = []
138
+ try {
139
+ labels = fs.readdirSync(configDir(), { withFileTypes: true })
140
+ .filter((e) => e.isDirectory())
141
+ .map((e) => e.name)
142
+ } catch (e) {
143
+ return []
144
+ }
145
+ const out = []
146
+ for (const label of labels) {
147
+ const dir = path.join(configDir(), label)
148
+ let names = []
149
+ try { names = fs.readdirSync(dir).filter((n) => n.endsWith(".json")) } catch (e) { continue }
150
+ for (const name of names) {
151
+ const data = readJson(path.join(dir, name))
152
+ if (data && data.access_token && data.endpoint) out.push(decorate(data, name.slice(0, -5)))
153
+ }
154
+ }
155
+ return out.sort((a, b) => String(b.created_at || "").localeCompare(String(a.created_at || "")))
156
+ }
157
+
158
+ /**
159
+ * Every session matching an org reference.
160
+ *
161
+ * `acme` matches on any environment (and on the org's slug or immutable id);
162
+ * `acme@staging` is pinned to one. Returning all matches rather than guessing
163
+ * lets the caller report the ambiguity instead of silently picking a tenant.
164
+ */
165
+ function matchSessions(ref) {
166
+ const wanted = String(ref == null ? "" : ref).trim()
167
+ if (!wanted) return []
168
+ const at = wanted.lastIndexOf("@")
169
+ const org = at > 0 ? wanted.slice(0, at) : wanted
170
+ const env = at > 0 ? wanted.slice(at + 1) : null
171
+
172
+ return allSessions().filter((s) => {
173
+ const isOrg = s.key === org || (s.org && (s.org.slug === org || s.org.id === org))
174
+ if (!isOrg) return false
175
+ if (!env) return true
176
+ return s.env === env || s.endpoint === expandEndpoint(env)
177
+ })
178
+ }
179
+
180
+ // Environments that hold at least one session, for the display commands.
181
+ function listEnvironments() {
182
+ const byEndpoint = new Map()
183
+ for (const s of allSessions()) {
184
+ if (!byEndpoint.has(s.endpoint)) byEndpoint.set(s.endpoint, [])
185
+ byEndpoint.get(s.endpoint).push(s)
186
+ }
187
+ return [...byEndpoint.entries()].map(([endpoint, sessions]) => ({
188
+ endpoint,
189
+ label: envLabel(endpoint),
190
+ alias: aliasOf(endpoint),
191
+ sessions
192
+ }))
193
+ }
194
+
195
+ // ---- writing sessions -------------------------------------------------------
196
+
197
+ // Store a session for (endpoint, org). `bundle` is the OAuth token bundle;
198
+ // `about` carries what whoami reported about the grant. The id_token is dropped
199
+ // — it is a third secret the CLI never uses.
200
+ function writeSession(endpoint, org, bundle, about = {}) {
201
+ const key = safeName(org)
202
+ const { id_token, ...tokens } = bundle || {}
203
+ const created = new Date()
204
+ const session = {
205
+ endpoint,
206
+ org: about.org || null,
207
+ account: about.account || null,
208
+ role: about.role || null,
209
+ ...tokens,
210
+ created_at: created.toISOString(),
211
+ expires_at: tokens.expires_in
212
+ ? new Date(created.getTime() + Number(tokens.expires_in) * 1000).toISOString()
213
+ : null
214
+ }
215
+ writeJson(sessionFile(endpoint, key), session)
216
+ return decorate(session, key)
217
+ }
218
+
219
+ // Merge fresh token fields into an existing session, preserving what the sign-in
220
+ // learned (org, account, role) and never resurrecting a deleted file.
221
+ function updateSession(endpoint, org, patch) {
222
+ const file = sessionFile(endpoint, org)
223
+ const existing = readJson(file)
224
+ if (!existing) return null
225
+ const { id_token, ...fields } = patch || {}
226
+ const next = { ...existing, ...fields, updated_at: new Date().toISOString() }
227
+ if (fields.expires_in) {
228
+ next.expires_at = new Date(Date.now() + Number(fields.expires_in) * 1000).toISOString()
229
+ }
230
+ // A refresh that doesn't rotate the refresh token must not erase ours.
231
+ if (!next.refresh_token && existing.refresh_token) next.refresh_token = existing.refresh_token
232
+ writeJson(file, next)
233
+ return decorate(next, safeName(org))
234
+ }
235
+
236
+ // Delete one already-resolved session.
237
+ function removeSession(session) {
238
+ if (!session || !session.endpoint) return null
239
+ try {
240
+ fs.unlinkSync(sessionFile(session.endpoint, session.key))
241
+ } catch (e) {
242
+ return null
243
+ }
244
+ // Leave no empty environment directories behind.
245
+ try { fs.rmdirSync(envDir(session.endpoint)) } catch (e) {}
246
+ return session
247
+ }
248
+
249
+ // ---- legacy layouts ---------------------------------------------------------
250
+
251
+ // Earlier layouts kept machine-wide state in ~/.known/config.json: first a
252
+ // `sessions` map keyed by endpoint, later just the selected endpoint. Neither
253
+ // has a place now that a session carries its own endpoint.
254
+ //
255
+ // A config holding only `current` is derived state with no secrets, so it is
256
+ // removed. One that still holds tokens is moved aside rather than dropped, since
257
+ // it can't be re-filed by org without knowing each token's org.
258
+ function legacyCleanup() {
259
+ const file = path.join(configDir(), "config.json")
260
+ const cfg = readJson(file)
261
+ if (!cfg) return null
262
+
263
+ const keys = Object.keys(cfg)
264
+ const holdsSecrets = !!(cfg.sessions || cfg.context || cfg.roles)
265
+ if (!holdsSecrets && keys.every((k) => k === "current")) {
266
+ try { fs.unlinkSync(file) } catch (e) { return null }
267
+ return { removed: file }
268
+ }
269
+
270
+ const backup = path.join(configDir(), "config.legacy.json")
271
+ try {
272
+ fs.renameSync(file, backup)
273
+ fs.chmodSync(backup, 0o600)
274
+ } catch (e) {
275
+ return null
276
+ }
277
+ return { backup }
278
+ }
279
+
280
+ module.exports = {
281
+ ENDPOINTS,
282
+ DEFAULT_ENDPOINT,
283
+ expandEndpoint,
284
+ aliasOf,
285
+ configDir,
286
+ envLabel,
287
+ envDir,
288
+ sessionFile,
289
+ listSessions,
290
+ allSessions,
291
+ matchSessions,
292
+ listEnvironments,
293
+ writeSession,
294
+ updateSession,
295
+ removeSession,
296
+ legacyCleanup
297
+ }