philolog

README

Philolog

Philolog is a Go library providing an immutable-style ledger for storing PII (Personally Identifiable Information) redaction records. Each new entry in the ledger triggers a cryptographic signing to ensure integrity and detect tampering.

Features

• PII Redaction Tracking: Store redaction details including text, start/stop positions, file name, and timestamp.
• Cryptographic Signing: Uses RSA with SHA256 to sign the ledger state.
• Verification: Built-in verification to detect unauthorized changes to the ledger's history.

Getting Started

Prerequisites

• Go 1.26.2+
• Docker (optional)
• MongoDB (optional)

Running the Server

Philolog includes a REST server. To start it with an in-memory ledger:

make run

The server will be available at http://localhost:8080.

An examples.sh script is provided to demonstrate using the server's endpoints:

./examples.sh

Using Docker

To build and run the Philolog server using Docker:

docker build -t philolog-server .
docker run -p 8080:8080 philolog-server

Using Docker Compose

For a complete setup including a MongoDB database:

docker compose up --build

Documentation

For more detailed information on the entry structure, API endpoints, environment variables, and programmatic usage, please see documentation.md.

License

Copyright 2026 Philterd, LLC. "Philolog" is a registered trademark of Philterd, LLC.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Index

• func AddEntry(store LedgerStore, entry Entry, privateKey *rsa.PrivateKey) error
• func Sign(store LedgerStore, privateKey *rsa.PrivateKey) error
• func Verify(store LedgerStore, publicKey *rsa.PublicKey) error
• type Entry
  • func (e Entry) Hash() ([]byte, error)
• type InMemoryLedger
  • func NewLedger() *InMemoryLedger
  • func (l *InMemoryLedger) AddEntry(entry Entry) error
  • func (l *InMemoryLedger) GetEntries() ([]Entry, error)
  • func (l *InMemoryLedger) GetEntriesPaged(offset, limit int) ([]Entry, error)
  • func (l *InMemoryLedger) GetLastEntry() (*Entry, error)
  • func (l *InMemoryLedger) GetSignature() ([]byte, error)
  • func (l *InMemoryLedger) SetSignature(signature []byte) error
• type LedgerStore
• type MongoDBLedger
  • func NewMongoDBLedger(ctx context.Context, uri string, dbName string, collectionName string) (*MongoDBLedger, error)
  • func (l *MongoDBLedger) AddEntry(entry Entry) error
  • func (l *MongoDBLedger) Close(ctx context.Context) error
  • func (l *MongoDBLedger) GetEntries() ([]Entry, error)
  • func (l *MongoDBLedger) GetEntriesPaged(offset, limit int) ([]Entry, error)
  • func (l *MongoDBLedger) GetLastEntry() (*Entry, error)
  • func (l *MongoDBLedger) GetSignature() ([]byte, error)
  • func (l *MongoDBLedger) SetSignature(signature []byte) error

Functions

func AddEntry

func AddEntry(store LedgerStore, entry Entry, privateKey *rsa.PrivateKey) error

AddEntry adds a new entry to the ledger and signs it.

func Sign

func Sign(store LedgerStore, privateKey *rsa.PrivateKey) error

Sign signs the current state of the ledger's entries.

func Verify

func Verify(store LedgerStore, publicKey *rsa.PublicKey) error

Verify checks if the signature matches the current entries.

Types

type Entry

type Entry struct {
	Text         string    `json:"text"`
	Start        int       `json:"start"`
	Stop         int       `json:"stop"`
	FileName     string    `json:"file_name"`
	Timestamp    time.Time `json:"timestamp"`
	PreviousHash []byte    `json:"previous_hash"`
}

Entry represents a single redaction entry in the ledger.

func (Entry) Hash

func (e Entry) Hash() ([]byte, error)

Hash calculates the SHA-256 hash of an entry.

type InMemoryLedger

type InMemoryLedger struct {
	Entries   []Entry `json:"entries"`
	Signature []byte  `json:"signature,omitempty"`
}

InMemoryLedger is an in-memory implementation of the LedgerStore interface.

func NewLedger

func NewLedger() *InMemoryLedger

NewLedger creates a new in-memory ledger.

func (*InMemoryLedger) AddEntry

func (l *InMemoryLedger) AddEntry(entry Entry) error

AddEntry adds a new entry to the in-memory ledger.

func (*InMemoryLedger) GetEntries

func (l *InMemoryLedger) GetEntries() ([]Entry, error)

GetEntries returns all entries in the in-memory ledger.

func (*InMemoryLedger) GetEntriesPaged

func (l *InMemoryLedger) GetEntriesPaged(offset, limit int) ([]Entry, error)

GetEntriesPaged returns a slice of entries from the in-memory ledger based on offset and limit.

func (*InMemoryLedger) GetLastEntry

func (l *InMemoryLedger) GetLastEntry() (*Entry, error)

GetLastEntry returns the last entry in the in-memory ledger.

func (*InMemoryLedger) GetSignature

func (l *InMemoryLedger) GetSignature() ([]byte, error)

GetSignature returns the signature of the in-memory ledger.

func (*InMemoryLedger) SetSignature

func (l *InMemoryLedger) SetSignature(signature []byte) error

SetSignature sets the signature of the in-memory ledger.

type LedgerStore

type LedgerStore interface {
	AddEntry(entry Entry) error
	GetEntries() ([]Entry, error)
	GetEntriesPaged(offset, limit int) ([]Entry, error)
	GetLastEntry() (*Entry, error)
	SetSignature(signature []byte) error
	GetSignature() ([]byte, error)
}

LedgerStore defines the interface for ledger storage backends.

type MongoDBLedger

type MongoDBLedger struct {
	// contains filtered or unexported fields
}

MongoDBLedger is a MongoDB-backed implementation of the LedgerStore interface.

func NewMongoDBLedger

func NewMongoDBLedger(ctx context.Context, uri string, dbName string, collectionName string) (*MongoDBLedger, error)

NewMongoDBLedger creates a new MongoDB-backed ledger.

func (*MongoDBLedger) AddEntry

func (l *MongoDBLedger) AddEntry(entry Entry) error

AddEntry adds a new entry to the MongoDB ledger.

func (*MongoDBLedger) Close

func (l *MongoDBLedger) Close(ctx context.Context) error

Close closes the MongoDB client.

func (*MongoDBLedger) GetEntries

func (l *MongoDBLedger) GetEntries() ([]Entry, error)

GetEntries returns all entries in the MongoDB ledger.

func (*MongoDBLedger) GetEntriesPaged

func (l *MongoDBLedger) GetEntriesPaged(offset, limit int) ([]Entry, error)

GetEntriesPaged returns entries in the MongoDB ledger based on offset and limit.

func (*MongoDBLedger) GetLastEntry

func (l *MongoDBLedger) GetLastEntry() (*Entry, error)

GetLastEntry returns the last entry in the MongoDB ledger.

func (*MongoDBLedger) GetSignature

func (l *MongoDBLedger) GetSignature() ([]byte, error)

GetSignature returns the signature of the MongoDB ledger.

func (*MongoDBLedger) SetSignature

func (l *MongoDBLedger) SetSignature(signature []byte) error

SetSignature sets the signature of the MongoDB ledger.