-
Notifications
You must be signed in to change notification settings - Fork 5
/
pizauth.1
145 lines (145 loc) · 4.48 KB
/
pizauth.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
.Dd $Mdocdate: September 13 2022 $
.Dt PIZAUTH 1
.Os
.Sh NAME
.Nm pizauth
.Nd OAuth2 authentication daemon
.Sh SYNOPSIS
.Nm pizauth
.Sy Em command
.Sh DESCRIPTION
.Nm
requests, shows, and refreshes OAuth2 tokens.
It is formed of two
components: a persistent "server" which interacts with the user to obtain
tokens, and refreshes them as necessary; and a command-line interface which can
be used by other programs to show the OAuth2 token for a current account.
.Pp
The top-level commands are:
.Bl -tag -width Ds
.It Sy dump
Writes the current
.Nm
state to stdout: this can later be fed back into
.Nm
with
.Sy restore .
The dump format is stable within a pizauth major release (but not
across major releases) and stable across platforms, though it includes
timestamps that may be affected by clock drift on either the machine performing
.Sy dump
or
.Sy restore .
Clock drift does not not affect security, though it may cause dumped access
tokens to be refreshed unduly early or late upon a
.Sy restore .
Refreshed access tokens will then be refreshed at the expected intervals.
.Pp
Note that while the
.Sy dump
output may look like it is encrypted, it is trivial for an attacker to recover
access and refresh tokens from it: it is strongly recommended that you use
external encryption on the output so that your data cannot be compromised.
.It Sy info Oo Fl j Oc
Writes output about
.Nm
to stdout including: the cache directory path; the config file path; and
.Nm
version.
Defaults to human-readable output in an unspecified format that may change
freely between
.Nm
versions.
.Pp
.Fl j
specifies JSON output.
The
.Qq info_format_version
field is an integer value specifying the version of the JSON output: if
incompatible changes are made, this integer will be monotonically increased.
.It Sy refresh Oo Fl u Oc Ar account
Request a refresh of the access token for
.Em account .
Exits with 0 upon success.
If there is not currently a valid access or refresh token,
reports an error to stderr, initiates a new token request, and exits with 1.
Unless
.Fl u
is specified, the error will include an authorization URL.
Note that this command does not block and will not start a new refresh if one
is ongoing.
.It Sy reload
Reload the server's configuration.
Exits with 0 upon success or 1 if there is a problem in the configuration.
.It Sy restore
Reads previously dumped
.Nm
state from stdin and updates those parts of the current state it determines
to be less useful than the dumped state.
This does not change the running instance's configuration: any changes in
security relevant configuration between the dumping and restoring
.Nm
instances causes those parts of the dump to be silently ignored.
See
.Sy dump
for information about the dump format, timestamp warnings, and encryption
suggestions.
.It Sy revoke Ar account
Removes any token, and cancels any ongoing authentication, for
.Em account .
Note that OAuth2 provides no standard way of remotely revoking a token:
.Sy revoke
thus only affects the local
.Nm
instance.
Exits with 0 upon success.
.It Sy server Oo Fl c Ar config-file Oc Oo Fl dv Oc
Start the server.
If not specified with
.Fl c ,
.Nm
checks for the configuration file (in order) at:
.Pa $XDG_CONFIG_HOME/pizauth.conf ,
.Pa $HOME/.config/pizauth.conf .
The server will daemonise itself unless
.Fl d
is specified.
Exits with 0 if the server started successfully or 1 otherwise.
.Fl v
enables more verbose logging.
.Fl v
can be used up to 4 times, with each repetition increasing the quantity
of logging.
.It Sy show Oo Fl u Oc Ar account
If there is an access token for
.Em account ,
print that access token to stdout and exit with 0.
If there is not currently a valid access token, prints an error to stderr
and exits with 1.
If refreshing might obtain a valid access token, refreshing is initiated
in the background.
Otherwise (unless
.Fl u
is specified), the error will include an authorization URL.
Note that this command does not block: commands must expect that they might
encounter an error when showing an access token.
.It Sy shutdown
Shut the server down.
Note that shutdown occurs asynchronously: the server may still be alive for a
period of time after this command returns.
.It Sy status
Writes output about the current accounts and whether they have access tokens to
stdout. The format is human-readable and in an unspecified format that may
change freely between
.Nm
versions.
.El
.Sh SEE ALSO
.Xr pizauth.conf 5
.Pp
.Lk https://tratt.net/laurie/src/pizauth/
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Laurence Tratt Lk https://tratt.net/laurie/