@future-unknown/known 0.0.0-stage → 0.1.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.
- package/README.md +558 -2
- package/bin/known +156 -0
- package/lib/auth.js +206 -0
- package/lib/cmds/_audit.js +153 -0
- package/lib/cmds/_code.js +673 -0
- package/lib/cmds/_config.js +91 -0
- package/lib/cmds/_endpoints.js +58 -0
- package/lib/cmds/_feedback.js +44 -0
- package/lib/cmds/_help.js +70 -0
- package/lib/cmds/_login.js +50 -0
- package/lib/cmds/_logout.js +40 -0
- package/lib/cmds/_members.js +403 -0
- package/lib/cmds/_ping.js +49 -0
- package/lib/cmds/_post.js +103 -0
- package/lib/cmds/_rpc.js +86 -0
- package/lib/cmds/_sessions.js +68 -0
- package/lib/cmds/_sites.js +300 -0
- package/lib/cmds/_teams.js +270 -0
- package/lib/cmds/_whoami.js +76 -0
- package/lib/cmds/_wiki.js +1503 -0
- package/lib/cmds/org.js +85 -0
- package/lib/config.js +297 -0
- package/lib/helpers.js +371 -0
- package/lib/output.js +338 -0
- package/lib/project.js +100 -0
- package/package.json +50 -4
package/lib/cmds/org.js
ADDED
|
@@ -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
|
+
}
|