-- in managed-auth configurations, parsav_auth is a table which is directly
-- controlled by the parsav daemon and utilities themselves. in unmanaged
-- configuration, you will need to create your own view with the same fields
-- as this table
create table parsav_auth (
	aid bigint primary key default (1+random()*(2^63-1))::bigint,
		-- the AID is the value that links a session to its credentials,
		-- so the aid needs to be stable over time. if you don't have a
		-- convenient field to rely on in your own datasets, the best
		-- approach is to use digest(str,'sha256') from the pgcrypto
		-- extension to create a value that depends on the values of
		-- kind, cred, and a unique user ID from your own dataset (NOT
		-- uid, as the UID associated with a session will change when
		-- a user logs in for the first time).

	uid bigint,
		-- the UID links a credential set to an actor in the parsav
		-- database. if it is equal to 0 (but not null) a new actor
		-- will be created and associated with the authentication
		-- records bearing its name when that user first logs in 

	name text,
		-- this is the handle of the actor that will be created when
		-- a user first logs in with this as the username and one of
		-- its associated credentials. the field is otherwise unused.

	kind text not null, -- see parsav.md
	cred bytea,
	restrict text[],
		-- per-credential restrictions can be levelled, for instance
		-- to prevent a certain API key from being used to post tweets
		-- as that user, while allowing it to be used to collect data.
		-- if restrict is null, no restrictions will be applied.
		-- otherwise, it should be an array of privileges that will be
		-- permitted when authenticated via this credential.

	netmask cidr,
		-- if not null, the credential will only be valid when logging
		-- in from an IP address contained by this netmask.

	blacklist bool not null default false,
		-- if the credential matches, access will be denied, even if
		-- non-blacklisted credentials match. most useful with
		-- uid = null, kind = trust, cidr = (untrusted IP range)

	valperiod timestamp default now(),
		-- cookies bearing timestamps earlier than this point in time
		-- will be considered invalid and will not grant access
	
	comment text,
		-- a field the user can use to identify the specific credential,
		-- in order to aid credential management

	unique(name,kind,cred)
);
