drafts.txt

//    \\ SPIKE: Secure your secrets with SPIFFE.
//  \\\\\ Copyright 2024-present SPIKE contributors.
// \\\\\\\ SPDX-License-Identifier: Apache-2.0

------

## Postgres Setup

> **Future Work**
>
> Postgres setup will be done in the future.
> Don't worry about it that much for now.

Here are steps to set up Postgres for Ubuntu Linux:

Install Postgres:

```bash
sudo apt install postgres
```

Configure Postgres to listen everywhere:

```bash
sudo vim /etc/postgresql/$version/main/postgresql.conf
# change listen_address as follows:
# listen_address = '*'
```

Create database `spike`:

```bash
sudo -u postgres psql -c 'create database spike;';
```

Set a password for the postgres user:

```bash
ALTER USER postgres with encrypted password 'your-password-here';
```

Enable SSL:

```bash
sudo vim /etc/postgresql/16/main/pg_hba.conf

# Update the file and set your IP range accordingly.
# hostssl spike postgres 10.211.55.1/24 scram-sha-256
```

That's it. Your database is configured for local development.


------

CREATE TABLE IF NOT EXISTS admin_token (
	id INTEGER PRIMARY KEY CHECK (id = 1),
	nonce BLOB NOT NULL,
	encrypted_token BLOB NOT NULL,
	updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS key_recovery (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    nonce BLOB NOT NULL,
    encrypted_data BLOB NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS admin_recovery_metadata (
    id INTEGER PRIMARY KEY CHECK (id = 1),
	encrypted_root_key BLOB NOT NULL,
    token_hash BLOB NOT NULL,
    salt BLOB NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
const QueryUpsertKeyRecoveryInfo = `
INSERT INTO key_recovery (id, nonce, encrypted_data, created_at, updated_at)
VALUES (1, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
ON CONFLICT(id) DO UPDATE SET
	nonce = excluded.nonce,
	encrypted_data = excluded.encrypted_data,
	updated_at = excluded.updated_at
`

const QueryLoadKeyRecoveryInfo = `
SELECT nonce, encrypted_data
FROM key_recovery
WHERE id = 1


const QueryInsertAdminToken = `
INSERT INTO admin_token (id, nonce, encrypted_token, updated_at)
VALUES (1, ?, ?, CURRENT_TIMESTAMP)
ON CONFLICT(id) DO UPDATE SET
	nonce = excluded.nonce,
	encrypted_token = excluded.encrypted_token,
	updated_at = excluded.updated_at
`

const QuerySelectAdminSigningToken = `
SELECT nonce, encrypted_token
FROM admin_token
WHERE id = 1
`

------

// SpikePilotRecoveryFolder returns the path to the directory where Pilot stores
// recovery material for its root key.
func SpikePilotRecoveryFolder() string {
	homeDir, err := os.UserHomeDir()
	if err != nil {
		homeDir = "/tmp"
	}

	spikeDir := filepath.Join(homeDir, ".spike")

	// Create directory if it doesn't exist
	// 0700 because we want to restrict access to the directory
	// but allow the user to create db files in it.
	err = os.MkdirAll(spikeDir+"/recovery", 0700)
	if err != nil {
		panic(err)
	}

	// The data dir is not configurable for security reasons.
	return filepath.Join(spikeDir, "/recovery")
}

// SpikePilotRootKeyRecoveryFile returns the path to the file where Pilot stores
// the root key recovery file.
func SpikePilotRootKeyRecoveryFile() string {
	folder := SpikePilotRecoveryFolder()

	// The file path and file name are NOT configurable for security reasons.
	return filepath.Join(folder, ".root-key-recovery.spike")
}



--------------------------------------------------------------------------------
// StoreKeyRecoveryInfo stores encrypted key recovery information in the
// database. It marshals the provided KeyRecoveryData to JSON, encrypts it, and
// stores it along with the encryption nonce. The data is stored with a fixed
// Id as defined in the database schema.
//
// The method is thread-safe, using a mutex to prevent concurrent access.
//
// Returns an error if marshaling, encryption, or database operations fail.
func (s *DataStore) StoreKeyRecoveryInfo(
	ctx context.Context, data store.KeyRecoveryData,
) error {
	// encrypted with the root key anyway. If you encrypt root key with itself,
	// if you lose rootkey, you cannot get it back.

	s.mu.Lock()
	defer s.mu.Unlock()

	// Marshal the data to JSON
	jsonData, err := json.Marshal(data)
	if err != nil {
		return fmt.Errorf("failed to marshal key recovery data: %w", err)
	}

	// Encrypt the JSON data
	encrypted, nonce, err := s.encrypt(jsonData)
	if err != nil {
		return fmt.Errorf("failed to encrypt key recovery data: %w", err)
	}

	// Store in database with id=1 (as per DDL)
	_, err = s.db.ExecContext(ctx, ddl.QueryUpsertKeyRecoveryInfo,
		nonce, encrypted)
	if err != nil {
		return fmt.Errorf("failed to store key recovery data: %w", err)
	}

	return nil
}

// LoadKeyRecoveryInfo retrieves and decrypts key recovery information from the
// database. If no recovery information exists, it returns (nil, nil).
//
// The method is thread-safe, using a read lock to allow concurrent reads.
//
// Returns:
//   - The decrypted KeyRecoveryData if found and successfully decrypted
//   - nil, nil if no recovery data exists
//   - An error if database operations, decryption, or JSON unmarshaling fail
func (s *DataStore) LoadKeyRecoveryInfo(
	ctx context.Context,
) (*store.KeyRecoveryData, error) {
	s.mu.RLock()
	defer s.mu.RUnlock()

	var (
		nonce         []byte
		encryptedData []byte
	)

	err := s.db.QueryRowContext(
		ctx,
		ddl.QueryLoadKeyRecoveryInfo,
	).Scan(&nonce, &encryptedData)
	if err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			return nil, nil
		}
		return nil, fmt.Errorf("failed to load key recovery data: %w", err)
	}

	// Decrypt the data
	decrypted, err := s.decrypt(encryptedData, nonce)
	if err != nil {
		return nil, fmt.Errorf("failed to decrypt key recovery data: %w", err)
	}

	// Unmarshal into KeyRecoveryData struct
	var data store.KeyRecoveryData
	if err := json.Unmarshal(decrypted, &data); err != nil {
		return nil, fmt.Errorf(
			"failed to unmarshal key recovery data: %w", err,
		)
	}

	return &data, nil
}
func UpdateCache(
	source *workloadapi.X509Source, rootKeyFromState string,
) error {
	if source == nil {
		return errors.New("UpdateCache: got nil source")
	}


	client, err := net.CreateMtlsClientWithPredicate(
		source, auth.IsKeeper,
	)
	if err != nil {
		return err
	}

	md, err := json.Marshal(
		reqres.RootKeyCacheRequest{RootKey: rootKeyFromState},
	)
	if err != nil {
		return errors.New(
			"UpdateCache: failed to marshal request: " + err.Error(),
		)
	}

	_, err = net.Post(client, api.UrlKeeperWrite(), md)

	return err
}

func FetchFromCache(source *workloadapi.X509Source) (string, error) {
	if source == nil {
		return "", errors.New("FetchFromCache: got nil source")
	}


	client, err := net.CreateMtlsClientWithPredicate(
		source, auth.IsKeeper,
	)
	if err != nil {
		return "", err
	}

	md, err := json.Marshal(reqres.RootKeyReadRequest{})
	if err != nil {
		return "", errors.New(
			"FetchFromCache: failed to marshal request: " + err.Error(),
		)
	}

	data, err := net.Post(client, api.UrlKeeperRead(), md)
	if err != nil {
		return "", fmt.Errorf(
			"FetchFromCache: failed to post request: %w", err,
		)
	}
	var res reqres.RootKeyReadResponse

	if len(data) == 0 {
		return "", nil
	}

	err = json.Unmarshal(data, &res)
	if err != nil {
		return "", errors.New(
			"FetchFromCache: failed to unmarshal response: " + err.Error(),
		)
	}

	return res.RootKey, err
}


---------------------------------------------------

//
//select {
//case <-ticker.C:
//	keepers := env.Keepers()
//
//	shardsNeeded := 2
//	var shardsCollected [][]byte
//
//	for _, keeperApiRoot := range keepers {
//		u, _ := url.JoinPath(keeperApiRoot, "/v1/store/shard")
//
//		client, err := net.CreateMtlsClientWithPredicate(
//			source, auth.IsKeeper,
//		)
//		if err != nil {
//			log.Log().Info("tick", "msg",
//				"Failed to create mTLS client", "err", err)
//			continue
//		}
//
//		md, err := json.Marshal(reqres.ShardRequest{})
//		if err != nil {
//			log.Log().Info("tick", "msg",
//				"Failed to marshal request", "err", err)
//			continue
//		}
//
//		data, err := net.Post(client, u, md)
//		var res reqres.ShardResponse
//
//		if len(data) == 0 {
//			log.Log().Info("tick", "msg", "No data")
//			continue
//		}
//
//		err = json.Unmarshal(data, &res)
//		if err != nil {
//			log.Log().Info("tick", "msg",
//				"Failed to unmarshal response", "err", err)
//			continue
//		}
//
//		if len(shardsCollected) < shardsNeeded {
//			decodedShard, err := base64.StdEncoding.DecodeString(res.Shard)
//			if err != nil {
//				log.Log().Info("tick", "msg", "Failed to decode shard")
//				continue
//			}
//
//			// Check if the shard already exists in shardsCollected
//			shardExists := false
//			for _, existingShard := range shardsCollected {
//				if bytes.Equal(existingShard, decodedShard) {
//					shardExists = true
//					break
//				}
//			}
//			if shardExists {
//				continue
//			}
//
//			shardsCollected = append(shardsCollected, decodedShard)
//		}
//
//		if len(shardsCollected) >= shardsNeeded {
//			log.Log().Info("tick",
//				"msg", "Collected required shards",
//				"shards_collected", len(shardsCollected))
//
//			g := group.P256
//
//			firstShard := shardsCollected[0]
//			firstShare := secretsharing.Share{
//				ID:    g.NewScalar(),
//				Value: g.NewScalar(),
//			}
//			firstShare.ID.SetUint64(1)
//			err := firstShare.Value.UnmarshalBinary(firstShard)
//			if err != nil {
//				log.FatalLn("Failed to unmarshal share: " + err.Error())
//			}
//
//			secondShard := shardsCollected[1] secondShare := secretsharing.Share{
//				ID:    g.NewScalar(),
//				Value: g.NewScalar(),
//			}
//			secondShare.ID.SetUint64(2)
//			err = secondShare.Value.UnmarshalBinary(secondShard)
//			if err != nil {
//				log.FatalLn("Failed to unmarshal share: " + err.Error())
//			}
//
//			var shares []secretsharing.Share
//			shares = append(shares, firstShare)
//			shares = append(shares, secondShare)
//
//			reconstructed, err := secretsharing.Recover(1, shares)
//			if err != nil {
//				log.FatalLn("Failed to recover: " + err.Error())
//			}
//
//			// O: check for errors.
//			binaryRec, _ := reconstructed.MarshalBinary()
//
//			// ODO: check size 32bytes.
//
//			encoded := hex.EncodeToString(binaryRec)
//			state.Initialize(encoded)
//
//			log.Log().Info("tick", "msg", "Initialized backing store")
//			return
//		}
//
//		log.Log().Info("tick",
//			"msg", "Failed to collect shards... will retry",
//		)
//	case <-ctx.Done():
//		return
//	}
//}


--------------------------------------------------------------------------------

From chat logs:

> In a pinch, a spire-agent with unix attestor can identify individual users.
> This may just be enough for admin identification for initial
> bootstrapping/recovery purposes.

That's a good idea. The admin user should already have an SVID for
"their" user anyway.

For example the following entry identifies the user:

```text
# [exhibit 1:]

# Register SPIKE Pilot
spire-server entry create \
    -spiffeID spiffe://spike.ist/spike/pilot \
    -parentID "spiffe://spike.ist/spire-agent" \
    -selector unix:uid:"$(id -u)" \
    -selector unix:path:"$PILOT_PATH" \
    -selector unix:sha256:"$PILOT_SHA"
```

So the fact that the user can use the SPIKE Pilot (the `spike` binary)
indeed means that they are authenticated. They don't need a password to further
authenticate themselves. (reasoning: they cannot be that user unless they
log in to the unix box -- the trust boundary is the box itself)


> named admins. so, for most things you know who is doing what.
> JWT will handle this well, using something like Keycloak,
> Entra, github, gitlab, facebook, etc, etc.

^ that needs to be a user story on its own. We can start experimenting with
keycloak and see how it goes from there. An OIDC is an OIDC is an
OIDC anyway -- how different can they be :)

> traditional admin, needed when things go horribly wrong to
> reenable named admins. I'm thinking, SPIRE issued jwt/svid for
> a certain uid, on a certain machine

I think `[exhibit 1:]` is good enough to secure the traditional admin.

We can have a SPIFFE ID like `spiffe://spike.ist/spike/pilot/role/superuser`.
It does not even have to be a JWT SVID. Someone who can talk to SPIKE can
assign/unassign it.

So. If hell broke lose, I'll assign myself a superadmin SVID;
fix stuff, and then unregister that SVID.

For named admins, we'd need OIDC, which can wait for a while.
For now, one superadmin is good enough.

> A token isn't useful without someone vetting it....

Yes, and I agree that it's not worth introducing to complexity, unless either of us
want to found a TPM/human-id startup (which is not a bad idea ideed :))

> Thats the problem with passwords. Your trusting a human, with limited memory,
> with a string a machine cares about and hope it stays secure. Thats proven hard.

LOL, but agreed.

--

So in short, the above approach I think...

1. will eliminate need for password.
2. will push identifying the superadmin to their unix credentials
   (one who owns the box owns spike, provided someone who owns spire
    let them own spike -- I like the multi-level access approach.
    So if I have login access to the box, but not to SPIRE, then the SPIRE admin can
    remove my access if I turn out to be a bad superadmin :) -- but in reality
    I will be the alpha and the omega (both SPIRE admin and also linux user))
3. root key backup and rotation is figureoutable and FFS.
4. named admins are figureoutable and FFS.

--------------------------------------------------------------------------------

Idea: Inverting the root key flow
Current consensus: It's better to harden SPIKE Keepers instead

Details:

Inverting the key generation flow in SPIKE—having the Nexus generate the root
key, compute the shares, distribute them to the Keepers, initialize the database
backend, and then discard the root key—alters the threat model and introduces
new benefits and liabilities.


--------------------------------------------------------------------------------

login <token>
login -method=userpass username=myuser password=mypass
login -method=github token=<github-token>
login -method=aws role=myrole

put secret/myapp/config username=dbuser password=dbpass
put secret/myapp/config @config.json
put -custom-metadata=owner=ops -custom-metadata=env=prod secret/myapp/config username=dbuser
put -version=2 secret/myapp/config username=newuser

get secret/myapp/config
get -version=1 secret/myapp/config
get -field=username secret/myapp/config
get -format=json secret/myapp/config
metadata get secret/myapp/config

delete secret/myapp/config
delete -versions=1,2 secret/myapp/config
destroy -versions=1 secret/myapp/config

metadata delete secret/myapp/config
```

ist secret/
list -format=json secret/

patch secret/myapp/config password=newpass
patch secret/myapp/config @patch.json

policy write mypolicy policy.yaml

policy read mypolicy
policy list

policy delete mypolicy

token create -policy=mypolicy
token create -ttl=1h
token renew <token>
token lookup <token>
token revoke <token>

```bash
enable userpass
enable -path=users-temp userpass
auth disable userpass
```

```bash
operator seal
operator unseal <key>
operator seal -status
```


```bash
audit enable file file_path=/var/log/vault/audit.log
audit list

# Disable audit device
audit disable file/
```



























--------------------------------------------------------------------------------
// File: server/types.go
package server

import (
    "time"
)







// File: server/acl_service.go
package server

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "path"
    "regexp"
    "sync"

    "github.com/google/uuid"
    "github.com/gorilla/mux"
)

type ACLService struct {
    policies sync.Map
}

func NewACLService() *ACLService {
    return &ACLService{}
}

func (s *ACLService) RegisterRoutes(r *mux.Router) {
    r.HandleFunc("/v1/store/acl/policies", s.CreatePolicy).Methods("POST")
    r.HandleFunc("/v1/store/acl/policies", s.ListPolicies).Methods("GET")
    r.HandleFunc("/v1/store/acl/policies/{id}", s.GetPolicy).Methods("GET")
    r.HandleFunc("/v1/store/acl/policies/{id}", s.DeletePolicy).Methods("DELETE")
    r.HandleFunc("/v1/store/acl/check", s.CheckAccess).Methods("POST")
}

func (s *ACLService) CreatePolicy(w http.ResponseWriter, r *http.Request) {
    var req CreatePolicyRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // Validate policy
    if _, err := regexp.Compile(req.SpiffeIdPattern); err != nil {
        http.Error(w, "invalid spiffe_id_pattern", http.StatusBadRequest)
        return
    }

    policy := &Policy{
        ID:              uuid.New().String(),
        Name:            req.Name,
        SpiffeIdPattern: req.SpiffeIdPattern,
        PathPattern:     req.PathPattern,
        Permissions:     req.Permissions,
        CreatedAt:       time.Now(),
        CreatedBy:       r.Header.Get("X-User-ID"), // Assuming auth middleware sets this
    }

    s.policies.Store(policy.ID, policy)

    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(policy)
}


# ## A note for Mac OS users ##
#
# The SPIRE Unix Workload Attestor plugin generates selectors based on
# Unix-specific attributes of workloads.
#
# On Darwin (macOS), the following selectors are supported:
# * unix:uid: The user ID of the workload (e.g., unix:uid:1000).
# * unix:user: The username of the workload (e.g., unix:user:nginx).
# * unix:gid: The group ID of the workload (e.g., unix:gid:1000).
# * unix:group: The group name of the workload (e.g., unix:group:www-data).
#
# However, the following selectors are not supported on Darwin:
# * unix:supplementary_gid: The supplementary group ID of the workload.
# * unix:supplementary_group: The supplementary group name of the workload.
#
# ^ These selectors are currently only supported on Linux systems.
#
# Additionally, if the plugin is configured with discover_workload_path = true,
# it can provide these selectors:
# * unix:path: The path to the workload binary (e.g., unix:path:/usr/bin/nginx).
# * unix:sha256: The SHA256 digest of the workload binary (e.g., unix:sha256:3a6...).

func (s *ACLService) CheckAccess(w http.ResponseWriter, r *http.Request) {
    var req CheckAccessRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    matchingPolicies := []string{}
    allowed := false

    s.policies.Range(func(key, value interface{}) bool {
        policy := value.(*Policy)

        // Check if SPIFFE ID matches pattern
        matched, err := regexp.MatchString(policy.SpiffeIdPattern, req.SpiffeID)
        if err != nil || !matched {
            return true // continue iteration
        }

        // Check if path matches pattern
        if matched, _ := path.Match(policy.PathPattern, req.Path); !matched {
            return true
        }

        // Check if action is allowed
        for _, perm := range policy.Permissions {
            if perm == req.Action {
                matchingPolicies = append(matchingPolicies, policy.ID)
                allowed = true
                break
            }
        }

        return true
    })

    json.NewEncoder(w).Encode(CheckAccessResponse{
        Allowed:          allowed,
        MatchingPolicies: matchingPolicies,
    })
}

// Other handlers (ListPolicies, GetPolicy, DeletePolicy) omitted for brevity

--------------------------------------------------------------------------------

// File: client/acl_client.go
package client

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

type ACLClient struct {
    baseURL    string
    httpClient *http.Client
}

func NewACLClient(baseURL string) *ACLClient {
    return &ACLClient{
        baseURL: baseURL,
        httpClient: &http.Client{
            Timeout: 30 * time.Second,
        },
    }
}

func (c *ACLClient) CreatePolicy(ctx context.Context, req CreatePolicyRequest) (*Policy, error) {
    body, err := json.Marshal(req)
    if err != nil {
        return nil, fmt.Errorf("marshaling request: %w", err)
    }

    httpReq, err := http.NewRequestWithContext(
        ctx,
        "POST",
        fmt.Sprintf("%s/v1/store/acl/policies", c.baseURL),
        bytes.NewReader(body),
    )
    if err != nil {
        return nil, fmt.Errorf("creating request: %w", err)
    }

    httpResp, err := c.httpClient.Do(httpReq)
    if err != nil {
        return nil, fmt.Errorf("sending request: %w", err)
    }
    defer httpResp.Body.Close()

    if httpResp.StatusCode != http.StatusCreated {
        return nil, fmt.Errorf("unexpected status: %d", httpResp.StatusCode)
    }

    var policy Policy
    if err := json.NewDecoder(httpResp.Body).Decode(&policy); err != nil {
        return nil, fmt.Errorf("decoding response: %w", err)
    }

    return &policy, nil
}

func (c *ACLClient) CheckAccess(ctx context.Context, spiffeID, path, action string) (*CheckAccessResponse, error) {
    req := CheckAccessRequest{
        SpiffeID: spiffeID,
        Path:     path,
        Action:   action,
    }

    body, err := json.Marshal(req)
    if err != nil {
        return nil, fmt.Errorf("marshaling request: %w", err)
    }

    httpReq, err := http.NewRequestWithContext(
        ctx,
        "POST",
        fmt.Sprintf("%s/v1/store/acl/check", c.baseURL),
        bytes.NewReader(body),
    )
    if err != nil {
        return nil, fmt.Errorf("creating request: %w", err)
    }

    httpResp, err := c.httpClient.Do(httpReq)
    if err != nil {
        return nil, fmt.Errorf("sending request: %w", err)
    }
    defer httpResp.Body.Close()

    if httpResp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("unexpected status: %d", httpResp.StatusCode)
    }

    var resp CheckAccessResponse
    if err := json.NewDecoder(httpResp.Body).Decode(&resp); err != nil {
        return nil, fmt.Errorf("decoding response: %w", err)
    }

    return &resp, nil
}

// Example usage:
func Example() {
    client := NewACLClient("http://localhost:8080")
    ctx := context.Background()

    // Create a policy
    policy, err := client.CreatePolicy(ctx, CreatePolicyRequest{
        Name:            "web-servers",
        SpiffeIdPattern: "spiffe://example.org/web-server/.*",
        PathPattern:     "secrets/web/*",
        Permissions:     []string{"read", "list"},
    })
    if err != nil {
        panic(err)
    }

    // Check access
    resp, err := client.CheckAccess(ctx,
        "spiffe://example.org/web-server/001",
        "secrets/web/config",
        "read",
    )
    if err != nil {
        panic(err)
    }

    fmt.Printf("Access allowed: %v\n", resp.Allowed)
    fmt.Printf("Matching policies: %v\n", resp.MatchingPolicies)
}




--------------------------------------------------------------------------------

## DRAFTS

This is a random place to dump anything that can be improved, re-used, re-enabled.
Think of this as the River of Styx; where things go to be reborn.

--------------------------------------------------------------------------------

SHAMIR

// Create a new group (using ed25519 as an example)
g := ed25519.NewGroup(acl/policies:
  post:
    description: Create a new access policy
    request:
      body:
        policy_name: string
        spiffe_id_pattern: string  # Supports regex/prefix matching
        path_pattern: string       # Supports glob patterns
        permissions:
          - read
          - list
        metadata:
          created_by: string
          created_at: timestamp
    response:
      policy_id: string
      status: string

  get:
    description: List all policies
    response:
      policies:
        - policy_id: string
          policy_name: string
          spiffe_id_pattern: string
          path_pattern: string
          permissions: [string]
          metadata:
            created_by: string
            created_at: timestamp
            last_modified: timestamp

/v1/acl/policies/{policy_id}:
  get:
    description: Get specific policy details
  delete:
    description: Remove a policy
  put:
    description: Update a policy

# Policy Evaluation API (for internal use)
/v1/acl/check:
  post:
    description: Check if a SPIFFE ID has access to a path
    request:
      spiffe_id: string
      path: string
      action: string  # read/list
    response:
      allowed: boolean
      matching_policies: [string]  # List of policy IDs that granted access

# Example Policy Document
example_policy:
  policy_name: "web-servers-secrets"
  spiffe_id_pattern: "spiffe://example.org/web-server/*"
  path_pattern: "secrets/web/*"
  permissions:
    - read
    - list
  metadata:
    created_by: "admin@example.org"
    created_at: "2024-11-16T10:00:00Z"

--------------------------------------------------------------------------------

Audit Trail:

All actions are logged with timestamps and acting admin
Tracks who created each admin
Logs password resets and backup assignments

-----

Issue management:
* This is a tiny project; so it does not need a big fat issue manager.
  even a `to_do.txt` with every line in priority order is a good enough way
  to manage things.
* The development team (me, Volkan, initially) will use `to do` labels liberally
  to designate what to do where in the project.
* GitHub issues will be created on a "per need" basis.
* Also the community will be encouraged to create GitHub issues, yet it won't
  be the team's main way to define issues or roadmap.
* I believe this unorthodox way will provide agility.
* For documentation versions, redirect to tagged github snapshots.
======